225 lines
6.7 KiB
Markdown
225 lines
6.7 KiB
Markdown
# macOS → Linux Ubuntu Migration Design
|
|
|
|
**Date:** 2026-04-18
|
|
**Status:** Design Approved
|
|
**Approach:** A (Minimal Linux Migration - Remove macOS-specific code)
|
|
|
|
---
|
|
|
|
## 1. Overview
|
|
|
|
The TFM aInventory codebase was originally developed on macOS with hardcoded paths and platform-specific commands. The user has migrated development to Ubuntu Linux and requires all shell scripts and documentation to reflect this new platform.
|
|
|
|
**Goal:** Remove all macOS-specific code (git paths, Homebrew references, `ipconfig` commands) and replace with Linux-native equivalents.
|
|
|
|
**Scope:** 7 files (5 shell scripts + 3 documentation files)
|
|
**Risk:** Low (all changes are platform-agnostic Linux compatibility)
|
|
**Deployment:** Local development + Docker testing + standalone bare-metal support
|
|
|
|
---
|
|
|
|
## 2. Files & Changes
|
|
|
|
### 2.1 `.git_path`
|
|
|
|
**Current:**
|
|
```
|
|
/Library/Developer/CommandLineTools/usr/bin/git
|
|
```
|
|
|
|
**Change:**
|
|
```
|
|
git
|
|
```
|
|
|
|
**Why:** Linux uses standard `git` in system PATH via package manager. No custom location needed. The `save_version.py` script already handles fallback to `git` if `.git_path` doesn't exist, so this change is backwards-compatible.
|
|
|
|
---
|
|
|
|
### 2.2 `start_server.sh`
|
|
|
|
**Change 1 - Line 19 (Remove Homebrew PATH):**
|
|
|
|
Current:
|
|
```bash
|
|
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
|
|
```
|
|
|
|
Remove this line entirely. On Linux, npm/node are installed system-wide or via Node Version Manager (nvm), not Homebrew.
|
|
|
|
**Change 2 - Line 41 (Fix IP Detection):**
|
|
|
|
Current:
|
|
```bash
|
|
LOCAL_IP=$(ipconfig getifaddr en0 || ipconfig getifaddr en1 || echo "localhost")
|
|
```
|
|
|
|
New:
|
|
```bash
|
|
LOCAL_IP=$(hostname -I | awk '{print $1}')
|
|
```
|
|
|
|
**Why:**
|
|
- `ipconfig` is macOS-only command
|
|
- `hostname -I` returns all IPv4 addresses on Linux; `awk '{print $1}'` extracts the first one (primary interface)
|
|
- Fallback to `localhost` removed; on Linux, the primary interface is always available
|
|
|
|
---
|
|
|
|
### 2.3 `run_standalone.sh`
|
|
|
|
**Change - Line 61 (Fix IP Detection):**
|
|
|
|
Current:
|
|
```bash
|
|
else
|
|
LOCAL_IP=$(hostname -I | awk '{print $1}')
|
|
fi
|
|
```
|
|
|
|
✅ **No change needed** — this branch already correctly uses Linux commands. The non-Darwin path is correct; we just ensure it's the only path used going forward.
|
|
|
|
---
|
|
|
|
### 2.4 `AI_RULES.md`
|
|
|
|
**Change - Remove Section 7.5 "Git Infrastructure Hardening (v1.7.0)"**
|
|
|
|
Current Section 7.5 (lines 106-109):
|
|
```markdown
|
|
### 7.5 Git Infrastructure Hardening (v1.7.0)
|
|
To ensure deployment stability on macOS environments with potentially broken developer tool links (`xcode-select` errors):
|
|
- **Direct Binary Mapping:** The system bypasses path resolution by using a hardcoded direct link to the Git binary in `.git_path` (`/Library/Developer/CommandLineTools/usr/bin/git`).
|
|
- **Persistence Mandate:** This path is protected by mandatory AI rules and must never be removed or modified to ensure `save-version` and automated deployment scripts remain functional.
|
|
```
|
|
|
|
**Delete entirely.** This section is no longer applicable on Linux where `git` in system PATH is reliable.
|
|
|
|
---
|
|
|
|
### 2.5 `PROJECT_ARCHITECTURE.md`
|
|
|
|
**Change - Remove macOS reference in Section 7.5**
|
|
|
|
Current text (lines 106-109):
|
|
```markdown
|
|
### 7.5 Git Infrastructure Hardening (v1.7.0)
|
|
To ensure deployment stability on macOS environments with potentially broken developer tool links (`xcode-select` errors):
|
|
...
|
|
```
|
|
|
|
**Delete this entire subsection.** Replace Section 7.5 heading with a note:
|
|
|
|
```markdown
|
|
### 7.5 Git Infrastructure (Linux Native)
|
|
|
|
All git operations use the standard `git` command available in system PATH. On Linux systems, this is reliably provided by the git package via the system package manager.
|
|
```
|
|
|
|
---
|
|
|
|
### 2.6 `SESSION_STATE.md`
|
|
|
|
**Change - Update System State section (lines 84-85)**
|
|
|
|
Current:
|
|
```markdown
|
|
**Active AI Tools:**
|
|
- **Git Binary:** `/Library/Developer/CommandLineTools/usr/bin/git`
|
|
- **Environment:** Use `./backend/venv/` for python tasks.
|
|
```
|
|
|
|
New:
|
|
```markdown
|
|
**Active AI Tools:**
|
|
- **Git Binary:** `git` (system PATH, Linux native)
|
|
- **Environment:** Use `./backend/venv/` for python tasks.
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Impact Analysis
|
|
|
|
### 3.1 Development Workflow
|
|
- ✅ Local `./start_server.sh` execution → detects IP, starts services
|
|
- ✅ Git commands via `save_version.py` → uses system `git`
|
|
- ✅ Shell script portability → scripts now run on any Linux system
|
|
|
|
### 3.2 Docker Testing
|
|
- ✅ No impact. Docker containers have their own git binary and PATH
|
|
- ✅ `docker compose` commands unchanged
|
|
|
|
### 3.3 Standalone Deployment (Bare-Metal)
|
|
- ✅ `export_prod.sh` → generates bundles correctly
|
|
- ✅ `./deploy.sh` (in bundle) → runs on Linux servers
|
|
- ✅ `./start_server.sh` (in bundle) → detects local IP correctly on any Linux system
|
|
|
|
### 3.4 Git Operations
|
|
- ✅ `save_version.py` reads `.git_path`; falls back to `git` if file missing
|
|
- ✅ All git commands (`commit`, `branch`, `merge`) work via system PATH
|
|
|
|
---
|
|
|
|
## 4. Testing Plan
|
|
|
|
After implementation:
|
|
|
|
1. **Local Development:**
|
|
- Run `./start_server.sh` → Should detect local IP (e.g., `192.168.x.x` or `localhost`), start backend + frontend + proxies
|
|
- Access `https://<detected-ip>:8909` in browser → Verify app loads
|
|
|
|
2. **Git Operations:**
|
|
- Run `git log` → Verify git works system-wide
|
|
- Run `python3 scripts/save_version.py --minor` → Should increment version, create branch, merge to master
|
|
|
|
3. **Docker Testing:**
|
|
- Run `docker compose build && docker compose up -d` → Should build and run without errors
|
|
- Access `https://<your-ip>:8909` → Verify Docker deployment
|
|
|
|
4. **Standalone Bundle:**
|
|
- Run `./export_prod.sh` → Should generate `.zip` bundle
|
|
- Extract bundle and run `./start_server.sh` → Should work on a clean Ubuntu system
|
|
|
|
---
|
|
|
|
## 5. Files Modified Summary
|
|
|
|
| File | Lines | Type | Risk |
|
|
|------|-------|------|------|
|
|
| `.git_path` | 1 | Config | 🟢 Low |
|
|
| `start_server.sh` | 2 | Script | 🟢 Low |
|
|
| `run_standalone.sh` | 0 | Script | 🟢 Low (verify only) |
|
|
| `AI_RULES.md` | Delete 7.5 | Docs | 🟢 Low |
|
|
| `PROJECT_ARCHITECTURE.md` | Rewrite 7.5 | Docs | 🟢 Low |
|
|
| `SESSION_STATE.md` | Update 1 line | Docs | 🟢 Low |
|
|
|
|
**Total:** 6 files, ~15 line changes (mostly deletions/rewrites)
|
|
|
|
---
|
|
|
|
## 6. Rollback Plan
|
|
|
|
If needed, restore from git history:
|
|
```bash
|
|
git checkout HEAD~N -- .git_path start_server.sh AI_RULES.md PROJECT_ARCHITECTURE.md SESSION_STATE.md
|
|
```
|
|
|
|
All changes are isolated to platform configuration; no core logic is affected.
|
|
|
|
---
|
|
|
|
## 7. Next Steps (Writing-Plans)
|
|
|
|
1. Implement all 6 file changes
|
|
2. Test local development workflow
|
|
3. Test git operations
|
|
4. Test Docker deployment
|
|
5. Verify standalone bundle generation
|
|
6. Commit with message: "chore: migrate from macOS to Linux Ubuntu"
|
|
7. Update VERSION.json via `save-version` command
|
|
|
|
---
|
|
|
|
**Approval:** Design approved by user (2026-04-18)
|
|
**Ready for implementation:** YES
|