homelab-infra/docs/RESTORE_HANDBOOK.md

Restore Handbook - KalliLab CORE

Stand: 2026-05-07

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

• Report: /mnt/user/backups/restore-reports/vaultwarden-2026-05-07.md
• Nachweis:
  • Borg-Restore erfolgreich
  • Testcontainer startete
  • Login-Seite war erreichbar

Gitea

• Report: /mnt/user/backups/restore-reports/gitea-2026-05-07.md
• Nachweis:
  • Borg-Restore erfolgreich
  • Web-UI antwortete
  • SSH-Port reagierte

Paperless

• Report: /mnt/user/backups/restore-reports/paperless-2026-05-07.md
• Nachweis:
  • Borg-Datei-Restore erfolgreich
  • Paperless-Dump aus Borg importiert
  • Login-Seite war erreichbar
  • Test-DB enthielt 25 Dokumente

---

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

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:00:
  • Gitea
• jeder 2. Monat, 2. Samstag, 08:00:
  • Paperless

---

6. Betriebsmodi

V1

• validierte Bash-Host-Jobs
• Host-Job-Definitionen liegen im Repo
• Scheduler kann bereits echte Frische- und Restore-Checks fahren
• ntfy und Hermes-Auswertung folgen danach

V2

• ntfy bei Erfolg/Fehler
• Hermes liest Reports und baut Uebersichten
• zusaetzliche Rotation, Sammelreports und weitere Dienste

---

7. User Script Jobs auf Unraid

Die Vorlagen stehen in:

• ops/restore-tests/unraid-user-scripts.md

Host-Repo-Pfad:

/mnt/user/services/homelab

V1-Jobs:

1. restore-freshness-weekly
2. restore-vaultwarden-monthly
3. restore-gitea-monthly
4. restore-paperless-bimonthly

---

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/ops/restore-tests/run-restore-checks.sh freshness

Vaultwarden Restore-Check

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

Gitea Restore-Check

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

Paperless Restore-Check

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

Optional mit ntfy

bash /mnt/user/services/homelab/ops/restore-tests/run-restore-job-with-ntfy.sh freshness homelab-info

---

11. Naechste Ausbaustufen

1. Vollautomatik fuer Vaultwarden, Gitea und Paperless
2. ntfy-Meldungen fuer Erfolg/Fehler
3. Hermes-Zusammenfassung ueber vorhandene Reports
4. naechster Referenz-Restore fuer mail-archiver oder mealie