# Native Immich on the M1 mini — status 2026-10-02 (late night)

**Target: Immich v3.2.4, no Docker anywhere.** DB migrated (144,884 assets from iMac v3.1 → mini v3.2 schema). Server boots, migrations apply, but there is a **launchd + SMB I/O bug** being fixed tonight.

## What's installed on the mini (all done)
- Homebrew: `postgresql@14` (v14.24), redis 8.10, node v24, pnpm 11.22
- pgvector **0.8.0** built for PG14 ✅, VectorChord **0.4.3** built + installed ✅
- PG14 data dir `/Users/yellowmellow/data/pg14`, superuser `immich`/`immich`, DB `immich`, extensions vchord+vector+cube+earthdistance, `shared_preload_libraries='vchord'`
- Immich v3.2.4 source `/Users/yellowmellow/src/immich` — server + web built (`web/build`, `server/dist`)
- Geodata pre-populated at `web/build/geodata/` (v3.2 requires it at startup; v3.1 tolerated absence)
- Env file `/Users/yellowmellow/immich/env`: `DB_URL`, `REDIS_URL`, `IMMICH_MEDIA_LOCATION=/Volumes/YellowMellowDrive/Immich`
- Media: SMB mount of iMac's 12TB drive (`//yellowmellow@192.168.2.111/YellowMellowDrive` → `/Volumes/YellowMellowDrive`) — same path strings as iMac, zero data moved
- Machine-learning service: not started (iMac also has ML disabled)

## Launchd agents created
| Label | What | State |
|---|---|---|
| `com.yellowmellow.postgres14` | brew postgres@14 | ✅ works |
| `com.yellowmellow.immich-server` | node launcher (loads env, forks API+microservice) | ⚠️ needs ssh-localhost wrapper (see below) |
| `com.yellowmellow.smb-mount` | mount_smbfs the drive at boot | ⚠️ works but needs kickstart after manual unmounts tonight |
| `com.yellowmellow.caffeinate` | sleep prevention | ✅ works |

## THE BUG (root-caused 2026-10-02)
**Symptom:** under launchd, server hangs in `storage.service.onBootstrap` → `verifyReadAccess('encoded-video')` → `fs.promises.readFile()` on the SMB mount **never settles** (promise pending forever, 0% CPU). All other startup fine. Migrations ✅, API boots ✅ — but mount check deadlocks and the whole bootstrap stalls; advisory lock 300 (SystemFileMounts) held forever, second worker waits.

**Isolation results:**
- Same readFile in a plain `node -e` from an **ssh session**: 51ms ✅
- Same readFile in a plain `node -e` under **launchd** (`launchctl submit`): **hangs forever** ❌
- Shell `cat` on SMB under launchd: fine. So it's **libuv thread-pool I/O + SMB (smbfs) in a launchd context** — macOS session/credential-context issue, not Immich code.
- NFS tried as alternative: iMac nfsd runs but **resets connections** (macOS 15.5 server bug; exports file fixed to `/Volumes/YellowMellowDrive -alldirs 192.168.2.79`, nfsd enabled). Abandoned.
- Mounting from a launchd-domain process does NOT help (still hangs) — the issue is per-context, not per-mount.

**THE FIX: run Immich inside a real login session via `ssh localhost`:**
```
launchd agent → ssh -T -o BatchMode=yes -o StrictHostKeyChecking=accept-new localhost node ~/immich-start-server.js
```
- sshd creates a real login session → SMB libuv I/O works (probe: **13ms ✅**)
- mini has its own ed25519 key generated + added to `~/.ssh/authorized_keys` for this
- **TODO (pending, tunnel dropped):** update `com.yellowmellow.immich-server.plist` ProgramArguments to the ssh-localhost form (currently still `zsh -lc node ...`), kickstart smb-mount agent, bootstrap, verify UI 200 + all `TRACE-READFILE done` lines appear.

## Temp debug patches IN DIST (remove after verification)
- `server/dist/services/storage.service.js` — TRACE-STORE/TRACE-VRA/TRACE-VWA console.error lines (backup: `storage.service.js.bak`)
- `server/dist/services/metadata.service.js` — TRACE-META lines (geodata lock)
- `server/dist/repositories/storage.repository.js` — TRACE-READFILE enter/done lines
Cleanup: `cp storage.service.js.bak storage.service.js`, revert metadata + repository traces (or just rebuild: `pnpm --filter @immich/server build`).

## iMac side (192.168.2.111)
- Immich v3.1 still running there (fallback; nothing touched on iMac processes)
- `/etc/exports` written for NFS attempts (harmless if unused): `/Volumes/YellowMellowDrive -alldirs 192.168.2.79`; `nfsd` enabled+running (can disable later: `sudo nfsd disable`)
- sudo works on iMac as yellowmellow (admin group, password known)

## End state once verified
- mini serves Immich v3.2.4 with full library, media over SMB from iMac drive
- next physical step (later): move 12TB drive into the mini → SMB becomes local, same paths, zero re-copy
- then: Caddy + point `immich.yellowmellowco.ca` at mini; christie admin account in web UI