Compare commits

..
Author SHA1 Message Date
finn.markwitzandClaude Opus 4.8 ae6c81bf54 fix(mibook): boot-menu terminal choice via specialisation
The previous startOnBoot approach booted mibook headless by default and
locked the machine out: it is WiFi-only with credentials in KWallet, so
with no desktop session NetworkManager never joins the network (no SSH),
and boot stalled on NetworkManager-wait-online with the tty1 prompt
buried under service logs.

Replace it with a NixOS specialisation that adds a separate 'terminal'
GRUB entry:
- default entry boots KDE as before (identical to baseline);
- 'terminal' entry boots multi-user.target with autologin for finn and a
  'desktop' command to start SDDM on demand.
Also disable NetworkManager-wait-online so boot never stalls on the
network. Revert the kde-desktop startOnBoot option.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CfozKLQdUh5TzqyjSigLUx
2026-07-27 10:52:18 +02:00
20 changed files with 168 additions and 736 deletions
+1 -3
View File
@@ -1,3 +1 @@
AGENTS.md AGENTS.md
*.dec
keys.txt
-17
View File
@@ -1,17 +0,0 @@
keys:
- &admin_finn age1a0v442ct2qfjcdhyktn25spw02yq4fl08plrrvuradwwxzsle4mq8thln4
- &host_mibook age1n3uqtee5ymykrls6k04dznq50cwmj99hw7ny83yxjndt4y2ncf5qhjwa2p
# - &host_jupiter age1... # TODO: Phase 9, see docs/secrets.md
creation_rules:
- path_regex: ^secrets/mibook\.yaml$
key_groups:
- age:
- *admin_finn
- *host_mibook
# - path_regex: ^secrets/jupiter\.yaml$ # TODO: Phase 9
# key_groups:
# - age: [ *admin_finn, *host_jupiter ]
# - path_regex: ^secrets/common\.yaml$ # TODO: Phase 9
# key_groups:
# - age: [ *admin_finn, *host_mibook, *host_jupiter ]
-12
View File
@@ -35,7 +35,6 @@ flake.nix
│ ├── core.nix # system packages, locale, timezone │ ├── core.nix # system packages, locale, timezone
│ ├── network.nix │ ├── network.nix
│ ├── nix.nix │ ├── nix.nix
│ ├── sops.nix # sops-nix decryption config, sops/age/ssh-to-age on PATH
│ └── users.nix │ └── users.nix
├── modules/ # custom NixOS option modules (my.profiles.*, my.hardware.*, my.services.*) ├── modules/ # custom NixOS option modules (my.profiles.*, my.hardware.*, my.services.*)
│ ├── environments/ # per-service/app profiles │ ├── environments/ # per-service/app profiles
@@ -44,21 +43,10 @@ flake.nix
└── machines/<name>/ └── machines/<name>/
├── configuration.nix # machine-specific NixOS settings ├── configuration.nix # machine-specific NixOS settings
├── environments.nix # enables profiles via my.profiles.* / my.hardware.* options ├── environments.nix # enables profiles via my.profiles.* / my.hardware.* options
├── secrets.nix # sops.secrets declared for this host
├── disks.nix ├── disks.nix
└── hardware-configuration.nix └── hardware-configuration.nix
``` ```
### Secrets (sops-nix)
Secrets are encrypted with sops, decrypted per-host from that host's SSH host
key. `.sops.yaml` defines who can decrypt what; `secrets/<host>.yaml` holds
the encrypted values; `machines/<host>/secrets.nix` declares which secrets
that host exposes and consumes them via `config.sops.secrets.<name>.path`.
Always `git add` a secrets file before `nix build` — untracked files are
invisible to flake evaluation. Full workflow (adding a secret, adding a host,
rotating keys): see [`docs/secrets.md`](docs/secrets.md).
### Profile / Module Pattern ### Profile / Module Pattern
Every module under `modules/` follows the same structure: Every module under `modules/` follows the same structure:
-92
View File
@@ -1,92 +0,0 @@
# Secrets (sops-nix)
Secrets are encrypted with [sops](https://github.com/getsops/sops) and decrypted
at activation by [sops-nix](https://github.com/Mic92/sops-nix). Each host decrypts
with its own SSH host key (converted to an age key in-memory — no separate host
private key is ever stored on disk).
Tooling (`sops`, `age`, `ssh-to-age`) is available via `nix develop` in this repo,
and installed system-wide on every machine via `machines/core/sops.nix`.
## Adding a secret to an existing host
```
nix develop -c sops secrets/<host>.yaml
```
This opens `$EDITOR` on the decrypted content. Add your key, save, quit — sops
re-encrypts on write. Then declare it in `machines/<host>/secrets.nix`:
```nix
sops.secrets.my-secret = {
owner = "someuser"; # defaults to root
group = "someuser";
mode = "0400";
restartUnits = [ "foo.service" ]; # if a running service needs to pick it up
};
```
Consume it in the owning module as `config.sops.secrets.my-secret.path`
(resolves to `/run/secrets/my-secret`) — never inline the decrypted value into
a Nix string, since that copies it into the world-readable `/nix/store`.
Then:
```
nix build '.#nixosConfigurations.<host>.config.system.build.toplevel'
sudo nixos-rebuild test --flake '.#<host>'
# verify, then:
sudo nixos-rebuild switch --flake '.#<host>'
```
**The secrets file must be `git add`ed before `nix build`** — untracked files
are invisible to flake evaluation, and `sops.validateSopsFiles` needs it in the
Nix store.
## Adding a new host
1. On the new host: `ssh-to-age < /etc/ssh/ssh_host_ed25519_key.pub` to get its
age public key.
2. In `.sops.yaml`: add a `&host_<name>` anchor with that key, and a
`creation_rules` entry for `secrets/<name>.yaml` including both the new
host key and `*admin_finn`.
3. Create `machines/<name>/secrets.nix`, add it to that machine's
`configuration.nix` imports.
4. If the host needs to read an existing shared file, run
`sops updatekeys secrets/<file>.yaml` after step 2 so it's re-encrypted to
include the new recipient.
## Rotating keys
```
# after editing .sops.yaml (new/removed recipient):
nix develop -c sops updatekeys secrets/<file>.yaml
```
for every file the change affects. `updatekeys` requires you to already be
able to decrypt the file — this is why `*admin_finn` is a recipient on every
rule, as the standing fallback.
Reinstalling a host regenerates its SSH host key, which changes its age
identity. Any file previously encrypted to that host must be `updatekeys`'d
with the new key, or the host's next activation fails to decrypt.
## Where private keys live
- **Operator** (you): `~/.config/sops/age/keys.txt` — sops' default lookup
path, so `SOPS_AGE_KEY_FILE` never needs to be set. Never committed. Back
this up out-of-band (password manager, offline copy) — if it's lost, only
the surviving host keys can still decrypt their own files, and any file that
was only ever readable by an operator-only rule becomes permanently
unreadable.
- **Hosts**: `/etc/ssh/ssh_host_ed25519_key` — already managed by NixOS,
converted to age in-memory at activation time. Nothing extra to back up.
## Layout
```
.sops.yaml # age recipients + creation rules (which keys can decrypt which files)
secrets/<host>.yaml # per-host encrypted secrets (default sopsFile for that host)
machines/core/sops.nix # applied to every machine: decryption config, sops/age/ssh-to-age on PATH
machines/<host>/secrets.nix # per-host: which secrets exist, owner/group/mode
```
@@ -1,299 +0,0 @@
# 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 <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.
@@ -0,0 +1,105 @@
# mibook: choose terminal-only vs desktop at boot
## Goal
Let mibook offer a choice, each time it boots, between the normal KDE desktop
and a terminal-only ("server") mode with no graphical session — decided at
boot, without rebuilding the system.
## Background: why the first attempt failed
The first implementation booted mibook to a text console by default
(`systemd.defaultUnit = "multi-user.target"`, display manager not started) and
provided a `desktop` command to start KDE on demand. On real hardware this
locked the machine out:
- **No SSH.** mibook is WiFi-only and its WiFi credentials are stored per-user
in KWallet ("agent-owned"). NetworkManager only receives the password once a
desktop session is running, so a headless boot never joins the network and
the machine has no IP — nothing to SSH into.
- **No usable console.** The boot appeared to "hang" with no login prompt:
`NetworkManager-wait-online` stalled waiting for a network that never came
up, and the `getty` login prompt on tty1 was buried under later service
messages.
Conclusion: a headless WiFi laptop cannot be reached remotely, and the plain
console was hard to use. The design must (a) keep the desktop as the reliable
default, (b) make the terminal path a deliberate, self-sufficient choice, and
(c) not depend on the network being up.
## Behavior
- The **default GRUB entry** boots straight into KDE — unchanged from the
known-working baseline.
- A **separate GRUB entry, `mibook (terminal)`** (a NixOS *specialisation*),
boots to a text console with **autologin** for `finn`. From there the user
can work in the shell or run `desktop` to bring KDE up (via SDDM).
- The choice is made in the GRUB menu at boot — matching the original request
to "decide each time I boot."
- Booting never stalls on the network.
### Known limitation (documented, not fixed in config)
In terminal mode WiFi will not connect on its own, because the password is
stored per-user in KWallet. To reach mibook over SSH from terminal mode, the
user must first save the WiFi as a **system** connection in KDE:
network settings → the WiFi network → "All users may connect to this network".
Until then, terminal mode is local-console-only. This is a one-time manual
step outside the scope of the Nix config.
## Implementation
### `machines/mibook/configuration.nix`
- Add a NixOS specialisation `specialisation.terminal.configuration`:
- `system.nixos.tags = [ "terminal" ];` — labels the generated boot entry.
- `systemd.defaultUnit = lib.mkForce "multi-user.target";` — boots to the
text console. `graphical.target` is what pulls in the display manager (via
its embedded `Wants=display-manager.service`), so defaulting to
`multi-user.target` leaves SDDM installed but not started at boot.
- `services.getty.autologinUser = "finn";` — guarantees a usable shell on
the console instead of a login prompt that can scroll off screen.
- A `desktop` command via
`pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service"`
in `environment.systemPackages`, to start KDE on demand.
- Add `systemd.services.NetworkManager-wait-online.enable = false;` (applies to
both the default and terminal boots) so boot never stalls waiting for the
network.
### Reverted from the first attempt
- `modules/environments/kde-desktop/default.nix` — remove the `startOnBoot`
option and its `mkMerge`/`mkIf` machinery; back to the original profile that
simply enables SDDM + Plasma 6.
- `machines/mibook/environments.nix` — remove `kde-desktop.startOnBoot = false;`
(back to just `kde-desktop.enable = true;`).
## Why a specialisation
A specialisation generates a second boot-menu entry automatically from a
modified copy of the configuration. It is the idiomatic NixOS mechanism for a
boot-time choice and avoids fragile hand-written GRUB `extraEntries` that would
need to track kernel/initrd paths across generations. The default entry remains
byte-for-byte the working desktop configuration.
## Testing / verification
- `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
builds both `nixos-system-mibook` and `nixos-system-mibook-terminal`.
- Verified on the built closures:
- Parent `default.target` → `graphical.target`; no console autologin
(identical to the pre-change baseline).
- Specialisation `default.target` → `multi-user.target`; tty1 getty wrapper
contains `--autologin finn`; `desktop` present in the system profile.
- `NetworkManager-wait-online` disabled in both.
- Post-`switch` manual check on mibook: default GRUB entry boots to KDE; the
`terminal` entry boots to an autologged-in console; running `desktop` there
starts SDDM and a working Plasma session.
## Trade-offs
- Autologin on the terminal console means physical access grants a shell
without a password. Acceptable for a personal laptop the user controls; the
desktop (default) boot is unaffected.
- `desktop` relies on `sudo`; the user has sudo access, so no extra config is
required.
@@ -1,121 +0,0 @@
# 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 | **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 |
| 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 <server> immich --version` or web UI footer).
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.
### Backup (before touching anything)
4. `docker compose down` (DB may stay up for the dump).
5. Dump DB: `docker exec -t <db> 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 — RESOLVED
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).
Generated
+21 -42
View File
@@ -21,11 +21,11 @@
"nixpkgs-lib": "nixpkgs-lib" "nixpkgs-lib": "nixpkgs-lib"
}, },
"locked": { "locked": {
"lastModified": 1785627969, "lastModified": 1782949081,
"narHash": "sha256-4dtXQk/NMePegK/nWp5NSeuZKLATItOq61lpEvmXqGw=", "narHash": "sha256-vp6Y/Grm98ESt6ceOkWiHWyZRDV3J1RID4w+6NWK9yA=",
"owner": "hercules-ci", "owner": "hercules-ci",
"repo": "flake-parts", "repo": "flake-parts",
"rev": "427bf4bd9435fdf21321c8cc628c24efc14c0f7a", "rev": "17c9d6cdfc60c64f4ee8d306f9bc0b4ccb51481e",
"type": "github" "type": "github"
}, },
"original": { "original": {
@@ -89,11 +89,11 @@
"nixpkgs-regression": "nixpkgs-regression" "nixpkgs-regression": "nixpkgs-regression"
}, },
"locked": { "locked": {
"lastModified": 1787274306, "lastModified": 1784762557,
"narHash": "sha256-Qg9f9td5iphUWSQS6zmvyZWO1F+D7j8Z3U6dGyUTg08=", "narHash": "sha256-R/r6jRnANV50c8F5Fz5+1Q1moab0IGWRk+cg5ME2nMY=",
"owner": "NixOS", "owner": "NixOS",
"repo": "nix", "repo": "nix",
"rev": "649e823fb24ed118d72e613be35fa8ea1b64afe7", "rev": "d10c84cd0cc0efdcb29cf2611caf5fbcd10fa071",
"type": "github" "type": "github"
}, },
"original": { "original": {
@@ -143,11 +143,11 @@
"nixpkgs": "nixpkgs_2" "nixpkgs": "nixpkgs_2"
}, },
"locked": { "locked": {
"lastModified": 1787144466, "lastModified": 1784723954,
"narHash": "sha256-HHfv2/HkNSKbbSyU9iD/g8lbP6r4tl33sSw1W4rXCk0=", "narHash": "sha256-1CfD8ZUjCkTgjsneLZ/lxCHhgDfqxxE7/GX0MmsgiqA=",
"owner": "NixOS", "owner": "NixOS",
"repo": "nixos-hardware", "repo": "nixos-hardware",
"rev": "0471accf8d0a8210b31d947497d179ecc99e0021", "rev": "a017f5b72210026af5b3ac5949f08d94380a6fbd",
"type": "github" "type": "github"
}, },
"original": { "original": {
@@ -187,11 +187,11 @@
}, },
"nixpkgs-lib": { "nixpkgs-lib": {
"locked": { "locked": {
"lastModified": 1785031560, "lastModified": 1782614948,
"narHash": "sha256-OmshNvn2vupOFpYinLUu+1Dnpu4n7Q5N3ggGVNHpkUI=", "narHash": "sha256-ePjCwr1sNm9NYUqywL7QfK3JnlS015msC+eBu2zKlp8=",
"owner": "nix-community", "owner": "nix-community",
"repo": "nixpkgs.lib", "repo": "nixpkgs.lib",
"rev": "0e79af5e3d4dcfcd676ab5ba3f95d2e3352e078c", "rev": "db3f255737b94216eb71cce308e2912cf6bc2d7c",
"type": "github" "type": "github"
}, },
"original": { "original": {
@@ -218,11 +218,11 @@
}, },
"nixpkgs-unstable": { "nixpkgs-unstable": {
"locked": { "locked": {
"lastModified": 1787135253, "lastModified": 1784796856,
"narHash": "sha256-M5/r2v++FjVhdsxXYMb4BDJ5YLAdCWFt3aZotcshocA=", "narHash": "sha256-vwxWgF+Gj276WznzGb1LxGsK/39HaQwgQXiU3EkC844=",
"rev": "ffb3c9b700e759be2ef13237c9d8f953b32a1e46", "rev": "e2587caef70cea85dd97d7daab492899902dbf5d",
"type": "tarball", "type": "tarball",
"url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1058091.ffb3c9b700e7/nixexprs.tar.xz" "url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1040357.e2587caef70c/nixexprs.tar.xz"
}, },
"original": { "original": {
"id": "nixpkgs", "id": "nixpkgs",
@@ -245,11 +245,11 @@
}, },
"nixpkgs_3": { "nixpkgs_3": {
"locked": { "locked": {
"lastModified": 1787101114, "lastModified": 1784707089,
"narHash": "sha256-BA7sSNjLDuPGSOYBGpr6WQjke1MQ8AZpJ8GlYZM/mOc=", "narHash": "sha256-DUedXhD2Rg8q4Xyd07Sb90eZGy4gg6W+Vl/WbLNwAZo=",
"rev": "b18a4b905f8d028dc4476412e6d6891728695379", "rev": "b3fe9581c9061c749abef42b6d4ee7b7c05c33fa",
"type": "tarball", "type": "tarball",
"url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.8045.b18a4b905f8d/nixexprs.tar.xz" "url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.5845.b3fe9581c906/nixexprs.tar.xz"
}, },
"original": { "original": {
"id": "nixpkgs", "id": "nixpkgs",
@@ -264,28 +264,7 @@
"nixos-generators": "nixos-generators", "nixos-generators": "nixos-generators",
"nixos-hardware": "nixos-hardware", "nixos-hardware": "nixos-hardware",
"nixpkgs": "nixpkgs_3", "nixpkgs": "nixpkgs_3",
"nixpkgs-unstable": "nixpkgs-unstable", "nixpkgs-unstable": "nixpkgs-unstable"
"sops-nix": "sops-nix"
}
},
"sops-nix": {
"inputs": {
"nixpkgs": [
"nixpkgs"
]
},
"locked": {
"lastModified": 1788337237,
"narHash": "sha256-gkSH8VUtCo6hnysNmb9DbTuDepH2t5pv+QWjP75xKAk=",
"owner": "Mic92",
"repo": "sops-nix",
"rev": "fbf759290e0cb0a98dfc813a4eb7d53ad1dacb57",
"type": "github"
},
"original": {
"owner": "Mic92",
"repo": "sops-nix",
"type": "github"
} }
} }
}, },
-13
View File
@@ -11,10 +11,6 @@
url = "github:nix-community/nixos-generators"; url = "github:nix-community/nixos-generators";
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
}; };
sops-nix = {
url = "github:Mic92/sops-nix";
inputs.nixpkgs.follows = "nixpkgs";
};
}; };
@@ -40,15 +36,6 @@
_module.args.pkgs = import inputs.nixpkgs { _module.args.pkgs = import inputs.nixpkgs {
inherit system; inherit system;
}; };
devShells.default = pkgs.mkShell {
packages = with pkgs; [
sops
age
ssh-to-age
nixfmt
];
};
}; };
systems = [ "x86_64-linux" ]; systems = [ "x86_64-linux" ];
-2
View File
@@ -4,7 +4,6 @@ let
nixpkgs nixpkgs
nixpkgs-unstable nixpkgs-unstable
nixos-hardware nixos-hardware
sops-nix
#hyprland #hyprland
; ;
nixosSystem = nixpkgs.lib.makeOverridable nixpkgs.lib.nixosSystem; nixosSystem = nixpkgs.lib.makeOverridable nixpkgs.lib.nixosSystem;
@@ -41,7 +40,6 @@ let
]; ];
} }
../modules ../modules
sops-nix.nixosModules.sops
# ../profiles # ../profiles
]; ];
defaultModules = baseModules ++ customModules; defaultModules = baseModules ++ customModules;
-1
View File
@@ -3,6 +3,5 @@
./modules.nix ./modules.nix
./network.nix ./network.nix
./nix.nix ./nix.nix
./sops.nix
./users.nix ./users.nix
] ]
-31
View File
@@ -1,31 +0,0 @@
# sops-nix plumbing — applied to every machine.
# See docs/secrets.md for the day-to-day workflow.
{
config,
lib,
pkgs,
...
}:
{
# Each host defaults to its own secrets/<hostname>.yaml. Override per-secret
# with sops.secrets.<name>.sopsFile for shared files.
sops.defaultSopsFile = lib.mkDefault (../../secrets + "/${config.networking.hostName}.yaml");
sops.defaultSopsFormat = "yaml";
sops.validateSopsFiles = true;
# Decrypt with the host's own SSH host key, converted to age.
# Explicit rather than inheriting the openssh-derived default, so this does
# not silently break if services.openssh is ever disabled.
sops.age.sshKeyPaths = [ "/etc/ssh/ssh_host_ed25519_key" ];
sops.age.generateKey = false;
# Age only. The default here is the RSA host key imported as a GPG key,
# which is deprecated and an extra failure surface.
sops.gnupg.sshKeyPaths = [ ];
environment.systemPackages = with pkgs; [
sops
age
ssh-to-age
];
}
+5 -2
View File
@@ -1,5 +1,9 @@
# enabled profiles # enabled profiles
_: { { config, lib, ... }:
let
secrets = config.sops.secrets;
in
{
my.profiles = { my.profiles = {
hyprland.enable = false; hyprland.enable = false;
zsh.enable = true; zsh.enable = true;
@@ -17,7 +21,6 @@ _: {
sonarr.enable = true; sonarr.enable = true;
jellyfin.enable = true; jellyfin.enable = true;
jellyseerr.enable = true; jellyseerr.enable = true;
immich.enable = true;
development.enable = true; development.enable = true;
home-assistant.enable = true; home-assistant.enable = true;
+31 -2
View File
@@ -10,8 +10,6 @@
./disks.nix ./disks.nix
./hardware-configuration.nix ./hardware-configuration.nix
./environments.nix ./environments.nix
./network.nix
./secrets.nix
# ./system.nix use docker here # ./system.nix use docker here
]; ];
@@ -44,6 +42,37 @@
services.openssh.enable = true; services.openssh.enable = true;
# Don't let boot stall waiting for a network that may never come up
# (WiFi credentials live in KWallet and need a desktop session), which
# otherwise hangs the terminal boot before the login prompt appears.
systemd.services.NetworkManager-wait-online.enable = false;
# Boot-time choice: the default GRUB entry boots straight into KDE.
# A separate "terminal" entry (a NixOS specialisation) boots to a text
# console with autologin, where you can work or run `desktop` to bring
# KDE up. Pick the entry you want in the GRUB menu at boot.
#
# NOTE: in terminal mode WiFi will not connect on its own (the password
# is stored per-user in KWallet). To reach the machine over SSH from
# terminal mode, first save the WiFi as a system connection in KDE:
# network settings -> your WiFi -> "All users may connect to this network".
specialisation.terminal.configuration = {
system.nixos.tags = [ "terminal" ];
# Boot to a text console. graphical.target is what pulls in the display
# manager (via its embedded Wants=display-manager.service), so defaulting
# to multi-user.target leaves SDDM installed but not started at boot.
systemd.defaultUnit = lib.mkForce "multi-user.target";
# Guarantee a usable shell on the console (no login prompt to hunt for).
services.getty.autologinUser = "finn";
# Bring the desktop up on demand from the terminal.
environment.systemPackages = [
(pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service")
];
};
# KDE (PowerDevil) power settings: do nothing on lid close while on AC power. # KDE (PowerDevil) power settings: do nothing on lid close while on AC power.
# Shipped as a system-wide default; KConfig cascades so a user's own # Shipped as a system-wide default; KConfig cascades so a user's own
# ~/.config/powerdevilrc will override this if present. # ~/.config/powerdevilrc will override this if present.
+5 -1
View File
@@ -1,5 +1,9 @@
# enabled profiles # enabled profiles
_: { { config, lib, ... }:
let
secrets = config.sops.secrets;
in
{
my.profiles = { my.profiles = {
kde-desktop.enable = true; kde-desktop.enable = true;
zsh.enable = true; zsh.enable = true;
-8
View File
@@ -1,8 +0,0 @@
_: {
# Athena (local AI): allow LAN access to the Hermes web dashboard.
# Bound to 0.0.0.0:9119 in the athena docker stack; NixOS default-deny
# firewall otherwise blocks inbound connections from other devices.
networking.firewall.allowedTCPPorts = [
9119 # athena hermes dashboard
];
}
-12
View File
@@ -1,12 +0,0 @@
# Secrets decrypted on mibook. sopsFile defaults to secrets/mibook.yaml
# via machines/core/sops.nix.
{ ... }:
{
# Pipeline smoke test — proves host-key decryption works end to end.
# Safe to delete once a real secret is in place.
sops.secrets.placeholder = {
mode = "0400";
owner = "root";
group = "root";
};
}
-1
View File
@@ -19,6 +19,5 @@
./sonarr ./sonarr
./jellyfin ./jellyfin
./jellyseerr ./jellyseerr
./immich
]; ];
} }
-52
View File
@@ -1,52 +0,0 @@
# 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" ];
# 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.
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";
}
];
};
}
-25
View File
@@ -1,25 +0,0 @@
placeholder: ENC[AES256_GCM,data:tji/6di1F2GsD60TEBGAVvZR9m4jxQ8=,iv:BoBQVR735vq38iGx40VHIpk185ylf79mKmnpewcq/+o=,tag:lXNNk4/HYB0sw44KaQ2KYg==,type:str]
sops:
age:
- enc: |
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA4ZUk5cjhGTlVveUFRdHdS
elpVV0pZVU54U3plYjNBai9ZZVBxTDhyRFFnCmpGWW81VGJoMnd4eWxCWnovQnFF
WXR1MVBTZ3VRUnNMUjI5Rko4NHpBdjQKLS0tIDkxYWNxTmhUS2dYTkFnTWZXaS9V
ejdtSmF2M1ZVdFNiWENMWlNraUYxVzAKdlz4xLhTKjJfFESDcym2xCOa71rXj6BE
mdeaCDhE11CAXqrpKU+j0/kwTsZRzyqlwQsfeI4ratu1K1vY66ONsw==
-----END AGE ENCRYPTED FILE-----
recipient: age1a0v442ct2qfjcdhyktn25spw02yq4fl08plrrvuradwwxzsle4mq8thln4
- enc: |
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBYT1hRSGt6TDRSMklQNDA3
Z2lYS2pMRWxxeEtGRGJSeXRDSlY5UTFBNEZvCm5RK0huT282MXpwWjdrTHByY3Ev
bTBMczR1MzVEcnNDVUxadlREbGg3UUUKLS0tIHhydUlmRExkbmNNNkVTcW1OSnpZ
aEtLZkRTRE9GZ0I1bEN0ZEl3RjVMeDgKoCY7NyxFMS+WuBUez2Irf91Xuy9QpM5g
RTmhK6mw2wd8oUMdgPOUESNwh1xkCz4hDHPrDQnfd4sPhSAvh28jwg==
-----END AGE ENCRYPTED FILE-----
recipient: age1n3uqtee5ymykrls6k04dznq50cwmj99hw7ny83yxjndt4y2ncf5qhjwa2p
lastmodified: "2026-09-08T13:29:12Z"
mac: ENC[AES256_GCM,data:YjMMIUdfCl8dkuvtvBZTFIhLwsUjI6iSeN929O4igbwpRTyGVxgLmAMl81YYHJSyEibelT7ZBKiuVVnL2KjLvAKTj3H1O+AQrcAEJDPC9NwPJwbtAIpLl2li5060Kdj4kr8AY+UJ2kHycuS9dg6wPZTLBJcM/YCw0AoVftvzryM=,iv:GEQZF9RvW+MJlMIjn1ToD74RubWMQtCyE5LqW9KQQfA=,tag:NR6u88eBY1asQZM6f45hTw==,type:str]
unencrypted_suffix: _unencrypted
version: 3.13.3