Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
Files
d48d4739423d10a07f69f8515e40f65ee57e0818
homelab-infra/docs/RESTORE_HANDBOOK.md
T
Micha c922d1f241 docs(restore): finalize audit - handbook update, reifegrad matrix, backlog 
Schliesst das Restore-Skills-Audit 2026-06-02/03 ab:

- RESTORE_HANDBOOK.md auf Stand 2026-06-03: alle 6 verifizierten Tests
  (Vaultwarden, Gitea, Paperless, Immich, Authelia, Komodo-Bootstrap)
  dokumentiert, Frequenz-Tabelle aktualisiert, Betriebsmodus auf V1+
  (mit ntfy), Schnellstart um Immich/Authelia/Komodo ergaenzt,
  Report-Aufbewahrungsregel dokumentiert, Ausbaustufen priorisiert.

- RESTORE_MATRIX.md: neue Sektion "Restore-Test-Reifegrad" mit
  Uebersichtstabelle (pro Dienst: Tier, letzter Test, Typ, naechster
  Lauf) und priorisierter Kandidatenliste fuer fehlende Tests.

- Gitea-Restore: SSH-Check im Report korrekt als "TCP connect only"
  benannt statt "SSH port open" (war Audit-Finding M3).

- AUDIT_2026-05-25_TODO.md: Restore-Audit-Backlog ergaenzt mit den
  verbleibenden 8 offenen Punkten (Nextcloud, Shared PG18, Komodo-Mongo,
  Mailarchiver, Mealie, Traefik, Negativ-Test, E2E-DR-Drill).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-03 09:31:19 +02:00

6.5 KiB
Raw Blame History

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/<dienst>
  • 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
    1. Samstag im Monat, 07:15: Gitea
    1. Samstag in ungeraden Monaten, 08:00: Paperless
    1. Sonntag in Feb/Mai/Aug/Nov, 08:30: Immich
    1. 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:

/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 /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh freshness

Vaultwarden Restore-Check

bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh vaultwarden

Gitea Restore-Check

bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh gitea

Paperless Restore-Check

bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh paperless

Immich Restore-Check

bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh immich

Authelia Restore-Check

bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh authelia

Komodo Bootstrap Trockenlauf

bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh komodo-bootstrap

Optional mit ntfy

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.

Reference in New Issue View Git Blame Copy Permalink