From 01b31a3493c2266e9e5c1bb6dc66d5674e7bab45 Mon Sep 17 00:00:00 2001 From: "Finn@MiBook" Date: Wed, 5 Aug 2026 16:32:46 +0200 Subject: [PATCH 1/5] =?UTF-8?q?docs:=20Immich=20docker=E2=86=92NixOS=20mod?= =?UTF-8?q?ule=20migration=20design?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_016e2PKH5yN31h6JgHWCQb32 --- .../2026-08-05-immich-nixos-module-design.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md diff --git a/docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md b/docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md new file mode 100644 index 0000000..c8ed56c --- /dev/null +++ b/docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md @@ -0,0 +1,119 @@ +# Immich: Docker → NixOS module migration + +**Date:** 2026-08-05 +**Machine:** jupiter (home server, Intel iGPU) +**Status:** Design approved, pending implementation plan + +## Goal + +Replace the existing docker-compose Immich deployment on jupiter with the +native `services.immich` NixOS module, wrapped in the repo's standard +`my.profiles.*` pattern. Preserve all existing data (albums, faces, shared +links, metadata) and photo/video library. + +## Decisions + +| Topic | Decision | +|-------|----------| +| Approach | Native `services.immich` (nixpkgs), not `oci-containers` | +| Version target | Stable nixpkgs ships **2.7.5**, unstable **3.0.3**. Pin target ≥ running docker version (forward-migration only) | +| Media location | Default local path `/var/lib/immich`. NAS deferred to a future read-only external library | +| Database | Migrate via dump/restore — keep everything | +| HW acceleration | Video transcoding only (VAAPI/QSV via existing Intel graphics stack). ML on CPU | +| Access | LAN + VPN only: open port 2283, register on homepage dashboard. No reverse proxy/TLS | + +### Deliberately deferred (YAGNI) +- OpenVINO ML acceleration +- NAS-backed external library +- Reverse proxy / TLS / public hostname + +## Part 1 — The module + +New file `modules/environments/immich/default.nix` following the profile +pattern; add `./environments/immich` to `modules/environments/default.nix`; +enable `my.profiles.immich.enable = true` in +`machines/jupiter/environments.nix`. + +```nix +{ config, lib, pkgs, ... }: +let + cfg = config.my.profiles.immich; + hostName = config.networking.hostName; + port = 2283; +in { + options.my.profiles.immich.enable = lib.mkEnableOption "Immich photo server"; + + config = lib.mkIf cfg.enable { + services.immich = { + enable = true; + # package = pkgs.unstable.immich; # only if docker :release is > 2.7.5 + 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}"; + }; + + # native module does not add GPU groups; needed 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"; + }]; + }; +} +``` + +**Provided for free by the native module:** local PostgreSQL with the required +vector extension over a **unix socket + peer auth** (so no DB password / sops +secret needed), Redis, `immich-server` and `immich-machine-learning` systemd +units, the `immich` system user, and `mediaLocation` created via tmpfiles. + +**Transcoding is two parts:** (a) NixOS exposes the GPU device + `video`/`render` +groups (above); (b) the hwaccel backend (QSV/VAAPI) is chosen in Immich's +**admin → video transcoding** settings after cutover — a UI toggle, not Nix. + +## Part 2 — Migration runbook (on jupiter) + +### Pre-flight (hard blocker) +1. Get running docker Immich version (`docker exec immich --version` or web UI footer). +2. Compare to target (stable 2.7.5 / unstable 3.0.3). Target **must be ≥ running**. + - running ≤ 2.7.5 → stable module as-is + - 2.7.6–3.0.3 → set `package = pkgs.unstable.immich` + - `> 3.0.3` → bump nixpkgs first; **stop and re-plan** +3. Record docker `UPLOAD_LOCATION` and DB container name/credentials. + +### Backup (before touching anything) +4. `docker compose down` (DB may stay up for the dump). +5. Dump DB: `docker exec -t pg_dumpall --clean --if-exists --username=postgres > immich-db.sql` +6. Verify upload folder intact; note size (no copy yet). + +### Cutover +7. Add the module to jupiter's `environments.nix` (leave `database.createDB` default). +8. `sudo nixos-rebuild switch --flake '.#jupiter'` → creates user, empty DB + role, `mediaLocation`. Then `systemctl stop immich-server immich-machine-learning`. +9. Restore the DB into the NixOS Postgres (drop the freshly-created empty `immich` DB, load `immich-db.sql`) per Immich's restore docs. +10. Move media into `/var/lib/immich` (subfolders `library/`, `upload/`, `thumbs/`, `encoded-video/`, `profile/`); `chown -R immich:immich /var/lib/immich`. +11. `systemctl start immich-server`; it runs schema migrations forward. Watch `journalctl -u immich-server -f`. + +### Verify +12. UI at `http://jupiter:2283` loads; log in; spot-check albums, faces, a shared link, and that thumbnails/originals actually load. +13. Homepage tile works. +14. Enable QSV/VAAPI in admin settings; transcode one video; confirm `journalctl` shows the hw path, not a CPU fallback error. + +### Rollback +Before deleting any docker data: `systemctl stop immich-*`, disable the profile, +`nixos-rebuild switch`, `docker compose up -d`. Original docker DB + upload +folder remain untouched until explicitly removed after a few days of confidence. + +## Known risk + +Step 9 crosses the **pgvecto.rs → VectorChord** vector-extension boundary if the +docker version predates VectorChord. Follow Immich's official "migrate vector +database" guidance during restore. The exact case is known only after the +pre-flight version check. From 117613262785d122a25b1c7b86dd180b9feddf8e Mon Sep 17 00:00:00 2001 From: "Finn@MiBook" Date: Wed, 5 Aug 2026 16:33:53 +0200 Subject: [PATCH 2/5] docs: resolve Immich version check (2.7.5 == stable, no vector migration) Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_016e2PKH5yN31h6JgHWCQb32 --- .../2026-08-05-immich-nixos-module-design.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md b/docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md index c8ed56c..f449c9f 100644 --- a/docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md +++ b/docs/superpowers/specs/2026-08-05-immich-nixos-module-design.md @@ -16,7 +16,7 @@ links, metadata) and photo/video library. | Topic | Decision | |-------|----------| | Approach | Native `services.immich` (nixpkgs), not `oci-containers` | -| Version target | Stable nixpkgs ships **2.7.5**, unstable **3.0.3**. Pin target ≥ running docker version (forward-migration only) | +| Version target | **Resolved: docker runs 2.7.5 == stable nixpkgs 2.7.5.** Use the stable module as-is; no `package` override. Same-version restore, no forward schema migration | | Media location | Default local path `/var/lib/immich`. NAS deferred to a future read-only external library | | Database | Migrate via dump/restore — keep everything | | HW acceleration | Video transcoding only (VAAPI/QSV via existing Intel graphics stack). ML on CPU | @@ -83,8 +83,9 @@ groups (above); (b) the hwaccel backend (QSV/VAAPI) is chosen in Immich's ### Pre-flight (hard blocker) 1. Get running docker Immich version (`docker exec immich --version` or web UI footer). -2. Compare to target (stable 2.7.5 / unstable 3.0.3). Target **must be ≥ running**. - - running ≤ 2.7.5 → stable module as-is +2. **Resolved 2026-08-05: running version is 2.7.5, equal to stable nixpkgs.** + Use the stable module as-is (no `package` override). Kept for reference: + - running ≤ 2.7.5 → stable module as-is ← **this case** - 2.7.6–3.0.3 → set `package = pkgs.unstable.immich` - `> 3.0.3` → bump nixpkgs first; **stop and re-plan** 3. Record docker `UPLOAD_LOCATION` and DB container name/credentials. @@ -111,9 +112,10 @@ Before deleting any docker data: `systemctl stop immich-*`, disable the profile, `nixos-rebuild switch`, `docker compose up -d`. Original docker DB + upload folder remain untouched until explicitly removed after a few days of confidence. -## Known risk +## Known risk — RESOLVED -Step 9 crosses the **pgvecto.rs → VectorChord** vector-extension boundary if the -docker version predates VectorChord. Follow Immich's official "migrate vector -database" guidance during restore. The exact case is known only after the -pre-flight version check. +The main risk was step 9 crossing the **pgvecto.rs → VectorChord** vector-extension +boundary. With source and target both at **2.7.5**, both use VectorChord — no +boundary crossing and no forward schema migration. The restore is a same-version +dump/load. Residual risk is limited to routine dump/restore mechanics +(roles, extension availability in the NixOS Postgres, ownership on restore). From 1f8a34d0e8c055abd8ed9b232b2a2f0de67ee054 Mon Sep 17 00:00:00 2001 From: "Finn@MiBook" Date: Wed, 5 Aug 2026 16:35:29 +0200 Subject: [PATCH 3/5] docs: Immich NixOS module implementation plan Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_016e2PKH5yN31h6JgHWCQb32 --- .../plans/2026-08-05-immich-nixos-module.md | 299 ++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-05-immich-nixos-module.md diff --git a/docs/superpowers/plans/2026-08-05-immich-nixos-module.md b/docs/superpowers/plans/2026-08-05-immich-nixos-module.md new file mode 100644 index 0000000..44d3577 --- /dev/null +++ b/docs/superpowers/plans/2026-08-05-immich-nixos-module.md @@ -0,0 +1,299 @@ +# 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`: + +```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: + +```nix + 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** + +```bash +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 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 pg_dumpall --clean --if-exists --username= > ~/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 ` 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`, ``, 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 `` into `/var/lib/immich`: +Run: `sudo rsync -aHAX --info=progress2 / /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 `` 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 `` 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 ``, ``, `` 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. From e9a578194469efe30cab4fce18e7039d0d6230cf Mon Sep 17 00:00:00 2001 From: "Finn@MiBook" Date: Wed, 5 Aug 2026 16:39:07 +0200 Subject: [PATCH 4/5] feat(jupiter): add native Immich profile module --- machines/jupiter/environments.nix | 1 + modules/environments/default.nix | 1 + modules/environments/immich/default.nix | 46 +++++++++++++++++++++++++ 3 files changed, 48 insertions(+) create mode 100644 modules/environments/immich/default.nix diff --git a/machines/jupiter/environments.nix b/machines/jupiter/environments.nix index c2ba90d..e36c825 100644 --- a/machines/jupiter/environments.nix +++ b/machines/jupiter/environments.nix @@ -21,6 +21,7 @@ in sonarr.enable = true; jellyfin.enable = true; jellyseerr.enable = true; + immich.enable = true; development.enable = true; home-assistant.enable = true; diff --git a/modules/environments/default.nix b/modules/environments/default.nix index eb0d299..9158f6a 100644 --- a/modules/environments/default.nix +++ b/modules/environments/default.nix @@ -19,5 +19,6 @@ ./sonarr ./jellyfin ./jellyseerr + ./immich ]; } diff --git a/modules/environments/immich/default.nix b/modules/environments/immich/default.nix new file mode 100644 index 0000000..f1b50f2 --- /dev/null +++ b/modules/environments/immich/default.nix @@ -0,0 +1,46 @@ +# 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"; + } + ]; + }; +} From 3ee2b1a9d816732d920e1aa7db1a7b11c6d52e75 Mon Sep 17 00:00:00 2001 From: "Finn@MiBook" Date: Fri, 7 Aug 2026 11:02:50 +0200 Subject: [PATCH 5/5] feat(immich): declare QSV transcoding via config-file settings Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_016e2PKH5yN31h6JgHWCQb32 --- modules/environments/immich/default.nix | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/modules/environments/immich/default.nix b/modules/environments/immich/default.nix index f1b50f2..46c6a51 100644 --- a/modules/environments/immich/default.nix +++ b/modules/environments/immich/default.nix @@ -24,7 +24,13 @@ in mediaLocation = "/var/lib/immich"; machine-learning.enable = true; accelerationDevices = [ "/dev/dri/renderD128" ]; - settings.server.externalDomain = "http://${hostName}:${toString port}"; + # Setting `settings` puts Immich in config-file mode: the admin settings + # UI becomes read-only and system config is managed declaratively here. + settings = { + server.externalDomain = "http://${hostName}:${toString port}"; + # Intel Quick Sync hardware transcoding (jupiter's iGPU). + ffmpeg.accel = "qsv"; + }; }; # The native module does not add GPU groups; required for VAAPI/QSV transcoding.