homelab-infra/docs/IMMICH_RESTORE_TEST.md

Immich Restore Test

Status: vorbereitet, noch nicht live ausgefuehrt (2026-05-26) Audit-Bezug: docs/AUDIT_2026-05-25.md Finding F-11

Zweck

Schliesst die Audit-Luecke aus F-11: Immich ist der groesste Datentopf (Familien-Fotos), und bisher gibt es im Gegensatz zu Vaultwarden, Gitea und Paperless keinen verifizierten Mini-Restore-Test. Dieses Dokument verlinkt die Repo-Artefakte und beschreibt den Ablauf aus Operator-Sicht.

Repo-Artefakte

Datei	Zweck
ops/restore-tests/immich-compose.test.yml	isoliertes Test-Compose: pgvecto-rs Postgres + Redis + Immich-Server, ML weggelassen, 127.0.0.1:12283
ops/restore-tests/immich-restore-test.sh	Host-Bash-Skript fuer den Lauf, mit --what-if und --keep-data Flags
ops/restore-tests/immich-restore-test.ps1	Plan-Scaffold fuer Windows-Operator-Sicht (kein Live-Run)
ops/restore-tests/immich-plan.md	Fachlicher Plan: Quellen, Schutzregeln, Smoke-Test-Kriterien, bekannte Risiken
ops/restore-tests/immich-runbook.md	Konkreter Operator-Ablauf, Fehlerfaelle, Schedule-Vorschlag

Was der Test abdeckt

• Extraktion von local/borg-dumps/latest/immich.dump aus dem aktuellsten Borg-Archiv
• Import in eine isolierte tensorchord/pgvecto-rs:pg14-v0.2.0 Postgres-Instanz mit demselben Digest wie Produktion
• Start eines isolierten Immich-Server-Containers mit demselben Digest wie Produktion, ohne ML-Container und ohne Traefik
• Smoke-Test: Login-Seite erreichbar, assets- und users-Tabelle lesbar
• Markdown-Report unter /mnt/user/backups/restore-reports/immich-YYYY-MM-DD.md
• Bereinigung von Test-Container und Restore-Lab-Daten nach Erfolg

Was der Test bewusst NICHT abdeckt

• Wiederherstellung produktiver Foto-Dateien (/mnt/user/photos/immich, /mnt/user/photos/family_archive). Diese Pfade werden vom Test nicht angefasst und nicht in den Test-Container gemountet.
• Machine-Learning-Container. Spart Image-Pull-Zeit und RAM; ML-Features sind im Smoke-Test irrelevant.
• Echte Login-Flow per API. Smoke-Test prueft nur, dass Login-Seite ausgeliefert wird.
• Asset-Rendering / Thumbnail-Generierung. Ohne Foto-Files erwartet.
• Produktive Domain immich.kaleschke.info. Test laeuft ausschliesslich auf 127.0.0.1:12283.

Restore-Stufe

Der Test deckt Stufe 4 (kritische Anwendungen) aus docs/DISASTER_RECOVERY.md Phase 4 fuer Immich ab, allerdings nur DB-Ebene und UI-Smoke. Voll-Restore inklusive Foto-Dateien aus Borg ist eigener Folgeschritt; das Skript bereitet die Restore-Lab-Struktur dafuer vor.

Vor dem ersten echten Lauf

Pruefung	Verantwortlich	Wo
Dump-Groesse von immich.dump bestimmen	Operator	ls -lh /mnt/user/backups/borg/dumps/latest/immich.dump
Freier Platz unter /mnt/user/backups/restore-lab/	Operator	df -h /mnt/user/backups
Borg-UI-Container laeuft	Operator	`docker ps
Trockenlauf mit --what-if	Operator	bash ops/restore-tests/immich-restore-test.sh --what-if
Erster echter Lauf mit --keep-data zur Zeitmessung	Operator	bash ops/restore-tests/immich-restore-test.sh --keep-data

Nach dem ersten erfolgreichen Lauf

1. Report unter /mnt/user/backups/restore-reports/immich-YYYY-MM-DD.md ueberpruefen.
2. docs/RESTORE_MATRIX.md um den Mini-Restore-Beleg ergaenzen (Datum + Reportpfad), analog zu Paperless 2026-05-07.
3. ops/restore-tests/schedule.md von "Immich spaeter" auf konkreten Quartals-Cron umstellen.
4. docs/AUDIT_2026-05-25_TODO.md F-11 von "offen" auf "erledigt" stellen.
5. docs/MIGRATION_LOG.md mit Mini-Lauf-Befund ergaenzen, ohne Secret-Werte.

Schutzregeln

• Skript greift ausschliesslich auf den Restore-Lab-Pfad und den Borg-Extract-Cache zu.
• Produktive Pfade unter /mnt/user/photos/* und /mnt/user/appdata/immich_postgres/ werden nicht angefasst.
• Produktive Container immich_server, immich_postgres, immich_redis, immich_machine_learning werden nicht gestoppt, nicht beruehrt.
• Borg-Passphrase wird aus /mnt/user/appdata/secrets/borg_repo_passphrase.txt gelesen und nicht in Reports, Logs oder Doku geschrieben.
• Test-Container publishen nur auf 127.0.0.1:12283, nicht auf LAN- oder Tailscale-Interface.
• Keine Traefik-Labels, keine Public-URL fuer Testcontainer.

Risiken (aus ops/restore-tests/immich-plan.md)

• Dump-Groesse und pg_restore-Dauer sind aktuell nicht gemessen.
• pgvecto-rs Extension-Mismatch bei Image-Drift moeglich; Compose pinnt denselben Digest wie Produktion.
• Immich-Server-Migrations koennen Startup nach Restore verzoegern; Skript pollt 120 s.
• Bei Schema-Drift (z. B. nach Major-Update) brechen einzelne DB-Queries; das Skript faengt das tolerant ab und schreibt n/a in den Report.

Naechste Operator-Schritte

1. Skript mit --what-if ausfuehren und den Plan-Output gegenpruefen.
2. Dump-Groesse und freien Platz pruefen.
3. Ersten echten Lauf mit --keep-data ausfuehren, Dauer messen.
4. Bei Erfolg: Restore-Matrix, Schedule, Audit-TODO und Migration-Log nachziehen.
5. Bei Fehler: Restore-Lab nicht selbst manuell bereinigen, sondern den Trap-Cleanup laufen lassen und ggf. Logs sichern, bevor erneut gestartet wird.