# 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