# Restore Handbook - KalliLab CORE Stand: 2026-06-03 Dieses Handbuch ist die praktische Betriebsanleitung fuer Restore-Checks und Restore-Lab in KalliLab CORE. Es ergaenzt: - `docs/RESTORE_MATRIX.md` - `docs/DISASTER_RECOVERY.md` - `ops/restore-tests/*` --- ## 1. Ziel Dieses Handbuch beantwortet vier Fragen: 1. Was ist die Restore-Quelle? 2. Wo wird getestet? 3. Wie pruefen wir Erfolg? 4. Wie machen wir das regelmaessig mit wenig Handarbeit? --- ## 2. Grundmuster Alle validierten Restore-Tests folgen demselben Muster: - Quelle bleibt das produktive Borg-Repo bei Hetzner - Borg-Zugriff laeuft ueber den vorhandenen `borg-ui`-Container - Passphrase kommt aus `/mnt/user/appdata/secrets/borg_repo_passphrase.txt` - Testdaten landen unter `/mnt/user/backups/restore-lab/` - Reports landen unter `/mnt/user/backups/restore-reports` - Testinstanzen laufen lokal ohne Traefik und ohne produktive Domain - nach Erfolg werden Testcontainer und Testdaten wieder entfernt --- ## 3. Bereits praktisch verifiziert ### Vaultwarden - Erstlauf: 2026-05-07 - Nachweis: Borg-Restore, Testcontainer, Login-Seite erreichbar ### Gitea - Erstlauf: 2026-05-07 - Nachweis: Borg-Restore, Web-UI, SSH-TCP-Port ### Paperless - Erstlauf: 2026-05-07, Folgelauf: 2026-05-31 - Nachweis: Borg-Datei-Restore, Dump-Import in Test-Postgres, Login-Seite, Doc-Count ### Immich - Erstlauf: 2026-05-27 - Nachweis: DB-Dump-Restore in VectorChord-Test-Postgres, HTTP-Smoke, Asset-Count - Hinweis: Foto-Dateien-Restore ist bewusst nicht Teil des Smokes ### Authelia - Erstlauf: 2026-06-03 - Nachweis: Config-Borg-Restore, `authelia config validate`, HTTP-Health `/api/health` - Hinweis: Daten-Restore des produktiven Dumps ist bewusst nicht Teil des Smokes (Storage-Encryption-Key-Kopplung) ### Komodo Bootstrap - Erstlauf: 2026-05-30 - Nachweis: Compose-Validierung, Mongo healthy, Core HTTP, Periphery running - Hinweis: Daten-Restore aus `komodo-mongo.archive.gz` ist noch nicht getestet --- ## 4. Verzeichnisstruktur ### Produktiv - `/mnt/user/appdata` - `/mnt/user/services` - `/mnt/user/documents` - `/mnt/user/backups/borg/dumps/latest` ### Restore-Lab - `/mnt/user/backups/restore-lab/vaultwarden` - `/mnt/user/backups/restore-lab/gitea` - `/mnt/user/backups/restore-lab/paperless` - `/mnt/user/backups/restore-lab/immich` - `/mnt/user/backups/restore-lab/authelia` - `/mnt/user/backups/restore-lab/komodo` - `/mnt/user/backups/restore-lab/_failed` (Diagnose-Material bei Fehllaeufen) ### Reports - `/mnt/user/backups/restore-reports` --- ## 5. Restore-Frequenz - jeden Montag, 06:30: Frische-Check fuer Dumps und Reports - 1. Samstag im Monat, 07:00: Vaultwarden - 3. Samstag im Monat, 07:15: Gitea - 2. Samstag in ungeraden Monaten, 08:00: Paperless - 2. Sonntag in Feb/Mai/Aug/Nov, 08:30: Immich - 2. Samstag in geraden Monaten, 07:30: Authelia - 1. Kalendertag im Monat, 09:00: Zufaelliger Restore aus Pool Vollstaendiger Kalender mit Cron-Ausdruecken und Shell-Guards steht in `ops/restore-tests/schedule.md`. --- ## 6. Betriebsmodus Stand 2026-06-03 ist der Betrieb auf V1+ (V1 mit ntfy): - validierte Bash-Host-Jobs fuer Vaultwarden, Gitea, Paperless, Immich, Authelia, Komodo-Bootstrap - Host-Job-Definitionen und Cron-Vorlagen liegen im Repo (`ops/restore-tests/unraid-user-scripts.md`) - `ntfy`-Wrapper sendet Erfolg an `homelab-info`, Fehler an `homelab-alerts` - Frische-Check prueft zusaetzlich pg-Custom-Format-Dumps per `pg_restore --list` Header-Validierung - bei Fehlschlag wird das Restore-Lab nach `_failed/` verschoben statt geloescht Noch geplant fuer V2: - Hermes-Zusammenfassung ueber vorhandene Reports - Sammelreports und Report-Rotation - weitere Dienste (Nextcloud, Mailarchiver, Mealie) --- ## 7. User Script Jobs auf Unraid Die Vorlagen stehen in: - `ops/restore-tests/unraid-user-scripts.md` Host-Repo-Pfad: ```text /mnt/user/services/homelab-infra ``` Jobs: 1. `restore-freshness-weekly` 2. `restore-vaultwarden-monthly` 3. `restore-gitea-monthly` 4. `restore-paperless-bimonthly` 5. `restore-immich-quarterly` 6. `restore-authelia-bimonthly` 7. `monthly-random-restore` --- ## 8. Erfolgskriterien Ein Restore-Test gilt nur dann als erfolgreich, wenn: - Restore-Quelle lesbar war - Daten im Restore-Lab ankamen - Testcontainer startete - Smoke-Test erfolgreich war - Report geschrieben wurde Nur `Container laeuft` reicht nicht. --- ## 9. Sicherheitsregeln - keine produktiven Pfade beschreiben - keine produktiven Container fuer Restore-Tests verwenden - keine produktiven Domains fuer Testinstanzen verwenden - keine Secrets im Repo - keine Restore-Automatik fuer neue Dienste ohne bewusste Freigabe --- ## 10. Schnellstart ### Frische-Check Auf dem Unraid-Host: ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh freshness ``` ### Vaultwarden Restore-Check ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh vaultwarden ``` ### Gitea Restore-Check ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh gitea ``` ### Paperless Restore-Check ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh paperless ``` ### Immich Restore-Check ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh immich ``` ### Authelia Restore-Check ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh authelia ``` ### Komodo Bootstrap Trockenlauf ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh komodo-bootstrap ``` ### Optional mit `ntfy` ```bash bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-job-with-ntfy.sh freshness homelab-info ``` --- ## 11. Naechste Ausbaustufen 1. Nextcloud-Restore-Test (mit `occ maintenance:mode`-Choreographie) 2. Mailarchiver-Restore-Test 3. Mealie-Restore-Test 4. Komodo-Mongo-Daten-Restore (echtes `mongorestore` statt reinem Bootstrap) 5. Shared-PostgreSQL-18-Cluster-Restore-Drill (globals + per-DB-Dumps) 6. Traefik-Restore-Test (mit `dynamic/` und LE-State) 7. Hermes-Zusammenfassung ueber vorhandene Reports 8. Report-Rotation (archivieren nach 12 Monaten) 9. Negativ-Test: bewusst kaputten Dump in den Frische-Check einfuettern ## 12. Report-Aufbewahrung Reports unter `/mnt/user/backups/restore-reports` werden dauerhaft aufbewahrt. Bei wachsender Anzahl (ca. 50-60 pro Jahr) empfiehlt sich eine jaehrliche Archivierung alter Reports in einen Unterordner `_archive/YYYY/`. Der Frische-Check warnt bei `MAX_REPORT_AGE_DAYS=45`, loescht aber bewusst nicht automatisch.