> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
>
> **Note on nature:** Task 1 is repo work verifiable with `nix build` (no runtime tests exist for declarative config). Tasks 2–6 are a **manual migration runbook executed on jupiter by the operator** — they are destructive and cannot be run from the dev machine (mibook). Do not attempt to automate or execute Tasks 2–6 from an agent session; present them for the operator to run and confirm.
**Goal:** Replace jupiter's docker-compose Immich with the native `services.immich` NixOS module, preserving all data (albums, faces, shares, library).
**Architecture:** A standard `my.profiles.immich` module wraps `services.immich` (native Postgres+VectorChord over unix socket, Redis, server, machine-learning). Media stays at the default local `/var/lib/immich`. The existing docker Postgres dump is restored same-version (2.7.5 → 2.7.5, no schema/vector migration). GPU is exposed for VAAPI/QSV transcoding.
- Produces: NixOS option `my.profiles.immich.enable` (bool). When true, configures `services.immich`, adds `immich` user to `video`/`render` groups, and appends an entry to `my.homepage.services`.
- [ ]**Step 1: Read a reference module to match repo style**
Read `modules/environments/jellyfin/default.nix` (same shape: `cfg`, `hostName`, `port`, `mkIf`, `my.homepage.services`). Match its formatting and header-comment convention.
# The native module does not add GPU groups; required for VAAPI/QSV transcoding.
users.users.immich.extraGroups=[
"video"
"render"
];
my.homepage.services=[
{
group="Media";
name="Immich";
description="Photo&videoserver";
href="http://${hostName}:${toStringport}";
icon="immich.png";
}
];
};
}
```
- [ ]**Step 3: Register the module in the environments import list**
Open `modules/environments/default.nix` and add `./environments/immich` (or `./immich`, matching the exact relative style already used in that file — check how `jellyfin` is listed and mirror it).
- [ ]**Step 4: Enable it on jupiter**
In `machines/jupiter/environments.nix`, inside the `my.profiles = { ... }` block, add:
Expected: builds successfully. If it fails on an unknown option (e.g. `accelerationDevices`, `settings.server.externalDomain`), reconcile against the module at `$(nix eval --raw '.#nixosConfigurations.jupiter.pkgs.path')/nixos/modules/services/web-apps/immich.nix` and fix.
### Task 2: Pre-flight & backup on jupiter (operator-run)
**Files:** none (runtime state on jupiter). Run all commands on jupiter.
**Interfaces:**
- Produces: `immich-db.sql` dump file and a known-good copy/snapshot of the docker upload folder; recorded `UPLOAD_LOCATION` path and DB container name.
- [ ]**Step 1: Record docker facts**
From the docker-compose dir on jupiter, note `UPLOAD_LOCATION`, the DB service/container name, and `POSTGRES_USER`/`POSTGRES_DB` from `.env`/compose. Confirm server version is **2.7.5** (web UI footer or `docker exec <server> immich --version`). If it is not 2.7.5, STOP — this plan assumes a same-version restore.
- [ ]**Step 2: Stop the docker stack (DB may stay up for the dump)**
Run: `docker compose stop immich-server immich-machine-learning` (leave the DB container running).
Expected: a non-trivial `immich-db.sql` (check it is not near-empty: `wc -l ~/immich-db.sql`).
- [ ]**Step 4: Stop the DB and record the media size**
Run: `docker compose down` then `du -sh <UPLOAD_LOCATION>` and note the size. Do NOT copy yet. Do NOT delete anything.
---
### Task 3: First switch — let the module create empty state (operator-run)
**Files:** none at runtime (repo change already committed in Task 1). Run on jupiter after pulling the committed branch.
**Interfaces:**
- Consumes: `immich-db.sql`, `UPLOAD_LOCATION` from Task 2.
- Produces: an `immich` system user, an empty `immich` Postgres DB + role, and `/var/lib/immich` created with correct ownership, with services then stopped.
- [ ]**Step 1: Deploy the config**
On jupiter, check out the branch containing Task 1's commit and run:
`sudo nixos-rebuild switch --flake '.#jupiter'`
Expected: `immich-server`, `immich-machine-learning`, postgres, and redis units come up; UI reachable at `http://jupiter:2283` showing a fresh/empty instance.
- [ ]**Step 2: Stop immich so data can be swapped underneath**
Expected: an `immich` database and `immich` role are present.
---
### Task 4: Restore database and media (operator-run, destructive)
**Files:** none in repo. Run on jupiter. This overwrites the freshly-created empty DB.
**Interfaces:**
- Consumes: `immich-db.sql`, `<UPLOAD_LOCATION>`, the running NixOS PostgreSQL.
- Produces: the migrated DB and populated `/var/lib/immich`.
- [ ]**Step 1: Restore the dump into the NixOS Postgres**
`pg_dumpall` output includes role/DB creation. Load it as the `postgres` superuser over the unix socket:
Run: `sudo -u postgres psql -f ~/immich-db.sql`
Expected: completes without fatal errors. Harmless "role already exists"/"database already exists" notices are OK because of `--clean --if-exists`. If the immich DB ends up owned by the wrong role, reassign: `sudo -u postgres psql -c 'ALTER DATABASE immich OWNER TO immich;'`.
Expected: a count matching your library size (non-zero). If the table name differs by version, list tables with `\dt` and check an obviously-populated one.
- [ ]**Step 3: Move the media into the default location**
Immich's upload folder holds subdirs `library/ upload/ thumbs/ encoded-video/ profile/ backups/`. Move (not copy, if same filesystem) the contents of `<UPLOAD_LOCATION>` into `/var/lib/immich`:
Expected: it connects to the DB, runs same-version startup checks (no destructive migration since 2.7.5==2.7.5), and reports listening on 2283. Leave the follow running through the next step.
Expected: active, no crash loop in `journalctl -u immich-machine-learning`.
- [ ]**Step 3: Functional spot-check in the web UI**
At `http://jupiter:2283`: log in with an existing account; confirm the timeline loads; open an **album**; open the **People/faces** view; open a **shared link**; open one photo so a **thumbnail and its full original both load** (this proves DB↔file paths align after the media move).
Expected: all present, images render.
- [ ]**Step 4: Confirm homepage dashboard tile**
Open the homepage dashboard; confirm the Immich tile appears under "Media" and links to `http://jupiter:2283`.
- [ ]**Step 5: Enable and verify hardware transcoding**
In Immich **Administration → Settings → Video Transcoding**, set hardware acceleration to **Quick Sync** (QSV) (or VAAPI). Trigger a transcode (upload/play a video that needs transcoding, or run the transcoding job). Then:
Expected: log shows the hardware path in use, not a CPU-fallback error. Confirm `/dev/dri/renderD128` is accessible to the service (the `video`/`render` groups + `accelerationDevices` from Task 1 handle this).
---
### Task 6: Sign-off and cleanup (operator-run)
**Files:** none in repo. Merge the branch; then, only after a confidence window, remove docker.
**Interfaces:**
- Consumes: a verified running instance (Task 5).
- [ ]**Step 1: Merge the feature branch**
Open a PR from `feat/immich-nixos-module` into `main` and merge it (repo convention: PRs via the Gitea remote).
- [ ]**Step 2: Confidence window**
Use Immich normally for a few days. Keep the docker `<UPLOAD_LOCATION>` source copy and `~/immich-db.sql` untouched as the rollback path.
- [ ]**Step 3: Rollback (only if needed, before cleanup)**
If something is wrong: `sudo systemctl stop immich-server immich-machine-learning`, set `immich.enable = false` (or check out the pre-migration commit), `sudo nixos-rebuild switch --flake '.#jupiter'`, then `docker compose up -d` in the old stack. Original docker DB + upload folder are intact until Step 4.
- [ ]**Step 4: Cleanup (after sign-off)**
Remove the docker Immich stack (`docker compose down --rmi all --volumes` in the old dir if the DB volume is dedicated — verify first), delete the now-duplicated `<UPLOAD_LOCATION>` source, and remove `~/immich-db.sql`. Optionally disable the `docker` profile on jupiter if Immich was its only consumer (check other services first — jupiter's `docker.enable` may still be needed).
---
## Self-Review
**Spec coverage:**
- Native `services.immich` → Task 1. ✓
- Version target 2.7.5==stable, no override → Global Constraints + Task 2 Step 1. ✓
- Media at default `/var/lib/immich` → Task 1 + Task 4 Step 3. ✓
**Placeholder scan:** No TBD/TODO; every command is concrete. Placeholders like `<db-container>`, `<UPLOAD_LOCATION>`, `<POSTGRES_USER>` are runtime values the operator reads in Task 2 Step 1 — intentional, not gaps.
**Type consistency:** Option name `my.profiles.immich.enable` and path `/var/lib/immich` used consistently across all tasks. Media subfolder list matches between Task 4 Step 3 and the spec.
# The native module does not add GPU groups; required for VAAPI/QSV transcoding.
users.users.immich.extraGroups=[
"video"
"render"
];
my.homepage.services=[
{
group="Media";
name="Immich";
description="Photo&videoserver";
href="http://${hostName}:${toStringport}";
icon="immich.png";
}
];
};
}
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
