nixos/docs/superpowers/plans/2026-08-05-immich-nixos-module.md

Immich NixOS Module Implementation Plan

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.

Tech Stack: NixOS (flake-parts), services.immich from nixpkgs 25.11, PostgreSQL, Intel QSV/VAAPI, docker (source only).

Global Constraints

• Machine: jupiter only. Do not enable on mibook.
• Immich version: source docker == target nixpkgs == 2.7.5 (stable). No package override. Do NOT bump nixpkgs Immich during this work.
• Media location: default /var/lib/immich (local disk). Do not point at the NAS.
• Database: local PostgreSQL over unix socket + peer auth — no password, no sops secret.
• HW accel: video transcoding only. ML stays on CPU (machine-learning.enable = true, no OpenVINO).
• Access: LAN + VPN, openFirewall = true, port 2283. No reverse proxy/TLS.
• Rebuild command: sudo nixos-rebuild switch --flake '.#jupiter'.
• Build-check command: nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel'.
• Format Nix with nixfmt-rfc-style before committing.
• Do not delete docker DB or upload data until Task 6 sign-off.

---

File Structure

• Create modules/environments/immich/default.nix — the my.profiles.immich module (single responsibility: declare Immich).
• Modify modules/environments/default.nix — add ./environments/immich to the import list.
• Modify machines/jupiter/environments.nix — set immich.enable = true.

No other files change. The DB/media migration touches only runtime state on jupiter, not the repo.

---

Task 1: Author the immich profile module

Files:

• Create: modules/environments/immich/default.nix
• Modify: modules/environments/default.nix (import list)
• Modify: machines/jupiter/environments.nix (my.profiles.immich.enable)

Interfaces:

• 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.

• Consumes: existing my.homepage.services aggregator; config.networking.hostName.

• 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.

• Step 2: Create the module file

Create modules/environments/immich/default.nix:

# Immich self-hosted photo & video server
{
  config,
  lib,
  pkgs,
  ...
}:
let
  cfg = config.my.profiles.immich;
  hostName = config.networking.hostName;
  port = 2283;
in
{
  options.my.profiles.immich = with lib; {
    enable = mkEnableOption "Immich photo server";
  };

  config = lib.mkIf cfg.enable {
    services.immich = {
      enable = true;
      host = "0.0.0.0";
      inherit port;
      openFirewall = true;
      mediaLocation = "/var/lib/immich";
      machine-learning.enable = true;
      accelerationDevices = [ "/dev/dri/renderD128" ];
      settings.server.externalDomain = "http://${hostName}:${toString port}";
    };

    # 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 & video server";
        href = "http://${hostName}:${toString port}";
        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:

    immich.enable = true;

• Step 5: Format

Run: nixfmt-rfc-style modules/environments/immich/default.nix

• Step 6: Build-check (this is the "test")

Run: nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel' 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.

• Step 7: Confirm the option evaluates on

Run: nix eval '.#nixosConfigurations.jupiter.config.services.immich.enable' Expected: true

• Step 8: Commit

git add modules/environments/immich/default.nix modules/environments/default.nix machines/jupiter/environments.nix
git commit -m "feat(jupiter): add native Immich profile module"

---

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).

• Step 3: Dump the database

Run: docker exec -t <db-container> pg_dumpall --clean --if-exists --username=<POSTGRES_USER> > ~/immich-db.sql 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

Run: sudo systemctl stop immich-server immich-machine-learning Expected: both inactive. PostgreSQL and Redis stay running.

• Step 3: Verify the DB and user exist

Run: sudo -u postgres psql -c '\l' | grep immich and sudo -u postgres psql -c '\du' | grep immich 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;'.

• Step 2: Sanity-check the restored data

Run: sudo -u postgres psql -d immich -c 'SELECT count(*) FROM assets;' 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: Run: sudo rsync -aHAX --info=progress2 <UPLOAD_LOCATION>/ /var/lib/immich/ (Use rsync — safe if partially interrupted. Keep the source until Task 6 sign-off.)

• Step 4: Fix ownership

Run: sudo chown -R immich:immich /var/lib/immich Expected: everything under /var/lib/immich owned by immich.

---

Task 5: Start and verify (operator-run)

Files: none. Run on jupiter.

Interfaces:

• Consumes: migrated DB + media from Task 4.

• Produces: a running, verified native Immich.

• Step 1: Start the server and watch logs

Run: sudo systemctl start immich-server && journalctl -u immich-server -f 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.

• Step 2: Start machine-learning

Run: sudo systemctl start immich-machine-learning 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: Run: journalctl -u immich-server | grep -iE 'qsv|vaapi|hwaccel|transcode' 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. ✓
• DB migrate keep-everything → Tasks 2–4. ✓
• HW transcoding only → Task 1 (accelerationDevices, groups) + Task 5 Step 5. ✓
• LAN+VPN, port 2283, openFirewall, homepage tile → Task 1 + Task 5 Steps 3–4. ✓
• Rollback path → Task 6 Step 3. ✓
• Deferred (OpenVINO/NAS/proxy) → correctly absent. ✓

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.