homelab-infra/docs/IMMICH_RESTORE_TEST.md

Immich Restore Test

Status: erfolgreich live verifiziert (2026-05-27) Audit-Bezug: docs/archive/2026-05/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: Immich-Postgres mit VectorChord + 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 ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.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, asset- und "user"-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.

Erster Lauf und Preflight

Pruefung	Verantwortlich	Wo
Dump-Groesse von immich.dump bestimmen	erledigt 2026-05-27	66M unter /mnt/user/backups/borg/dumps/latest/immich.dump
Freier Platz unter /mnt/user/backups/restore-lab/	erledigt 2026-05-27	ca. 3.7T frei auf /mnt/user/backups
Borg-UI-Container laeuft	Operator	`docker ps
Trockenlauf mit --what-if	erledigt 2026-05-27	Host-Clone auf c5d231a, bash ops/restore-tests/run-restore-checks.sh immich --what-if erfolgreich
Erster echter Lauf	erledigt 2026-05-27	Report /mnt/user/backups/restore-reports/immich-2026-05-27.md; Archiv Tägliche-Sicherung-2026-05-27T04:30:06.778; HTTP 200; Assets 11977; User 1

Nach dem ersten erfolgreichen Lauf

1. Report unter /mnt/user/backups/restore-reports/immich-2026-05-27.md liegt vor und ist erfolgreich.
2. docs/RESTORE_MATRIX.md, ops/restore-tests/schedule.md, docs/AUDIT_2026-05-25_TODO.md und docs/MIGRATION_LOG.md wurden nachgezogen.
3. Quartalsweise Wiederholung einplanen; erster Live-Lauf bleibt bewusst manuell/Operator-kontrolliert, bis mehrere Laeufe stabil waren.

Schutzregeln

• Skript greift ausschliesslich auf den Restore-Lab-Pfad und den Borg-Extract-Cache zu.
• Produktive Pfade unter /mnt/user/photos/*, /mnt/user/appdata/immich_postgres_vectorchord/ und dem Rollback-Altstand /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 erster pg_restore-Lauf sind gemessen: immich.dump 66M, echter Smoke-Test erfolgreich am 2026-05-27.
• VectorChord-/pgvector-Extension-Mismatch bei Image-Drift moeglich; Compose pinnt denselben Digest wie Produktion.
• Immich nutzt nach der VectorChord-Migration vchord 0.4.3 und vector 0.8.1; Restore-Tests muessen ein Image mit VectorChord verwenden.
• Immich-Server-Migrations koennen Startup nach Restore verzoegern; Skript pollt 120 s.
• Bei Schema-Drift (z. B. nach Major-Update) koennen einzelne DB-Queries abweichen; das Skript versucht Immich-v2-Singular-Tabellen und aeltere Plural-Fallbacks.

Naechste Operator-Schritte

1. Quartalsweise Wiederholung nach ops/restore-tests/schedule.md einplanen.
2. Bei zukuenftigem Immich-Major-Upgrade den Restore-Test unmittelbar danach einmal manuell ausfuehren.
3. Voll-Restore inklusive Foto-Dateien bleibt ein eigener, deutlich groesserer DR-Drill.