homelab-infra/docs/RESTORE_DRILL_ROUTINE.md

Restore-Drill Routine - KalliLab CORE

Status: verbindliche Routine (Doku-only), 2026-05-27. Audit-Bezug: docs/archive/2026-05/AUDIT_2026-05-25.md Sprint 7 "Restore-Lab-Drill quartalsweise dokumentieren". Verwandte Docs: docs/RESTORE_MATRIX.md, docs/RESTORE_HANDBOOK.md, docs/DISASTER_RECOVERY.md, ops/restore-tests/schedule.md.

Ziel

Sicherstellen, dass die Backup-Kette nicht nur weiter laeuft, sondern auch wiederherstellbar ist. Restore-Tests werden nicht ad-hoc gemacht, wenn ein Problem auftritt, sondern in einer planbaren Kadenz, damit das Vertrauen ueber die Zeit waechst und Drift fruehzeitig auffaellt.

Diese Datei beschreibt nur die Routine (wann, was, wie pruefen). Die operativen Anleitungen pro Dienst stehen in docs/RESTORE_HANDBOOK.md und den dienstspezifischen Runbooks unter ops/restore-tests/<dienst>-runbook.md.

Drei-Stufen-Modell

Stufe	Frequenz	Aufwand	Ziel
Freshness-Check	woechentlich	Minuten	Backup-Artefakte sind frisch, Reports lesbar
Mini-Restore	monatlich/quartalsweise	15-60 Min	Ein konkreter Dienst wird in isoliertem Test-Lab restauriert
DR-Sanity-Check	quartalsweise	1-2 h	Reihenfolge, Doku, Tier-Reihenfolge in der DR-Doku gegen Realitaet pruefen

Bestaetigte Mini-Restores

Wenn ein Mini-Restore zum ersten Mal sauber durchlaeuft, wird er hier als Referenz gefuehrt. Der Eintrag wird nicht entfernt, wenn er wiederholt wird; stattdessen aendert sich der Datums-Stand.

Dienst	Erster bestaetigter Lauf	Letzter Erfolg	Report	Repo-Skript
Vaultwarden	2026-05-07	2026-05-07	/mnt/user/backups/restore-reports/vaultwarden-2026-05-07.md	ops/restore-tests/vaultwarden-restore-test.sh
Gitea	2026-05-07	2026-05-07	/mnt/user/backups/restore-reports/gitea-2026-05-07.md	ops/restore-tests/gitea-restore-test.sh
Paperless	2026-05-07	2026-05-07	/mnt/user/backups/restore-reports/paperless-2026-05-07.md	ops/restore-tests/paperless-restore-test.sh
Immich	2026-05-27	2026-05-27	/mnt/user/backups/restore-reports/immich-2026-05-27.md	ops/restore-tests/immich-restore-test.sh

Bei jedem weiteren Lauf wird die Spalte "Letzter Erfolg" aktualisiert.

Quartals-Kadenz

Ein Kalenderjahr enthaelt vier Quartals-Drills. Jeder Quartals-Drill besteht aus dem Mini-Restore eines anderen Tier-2-Dienstes plus einem DR-Sanity-Check der Tier-1-Dienste.

Quartal	Mini-Restore	DR-Sanity-Check Fokus
Q1 (Januar-Maerz)	paperless	Tier-1-Reihenfolge, Posture-Check-Status, Borg-Frische-Alerts
Q2 (April-Juni)	immich	Komodo-Bootstrap-Pfad, Gitea-Bundles, Secrets-Pfad-Inventur
Q3 (Juli-September)	mealie oder nextcloud (Operator-Wahl)	DNS-Pfad (AdGuard/Unbound/Tailscale), Cert-Expiry-Sicht
Q4 (Oktober-Dezember)	vaultwarden oder gitea (Operator-Wahl)	Externe Abhaengigkeiten (Cloudflare, Hetzner, GitHub-Mirror), Off-site-Zweitziel-Diskussion

Diese Liste ist bewusst auf Tier-2 und Tier-1-Dienste fokussiert. Tier-3-Dienste (Filebrowser, Glances, Scrutiny, Speedtest, Glance) werden im Drill nicht explizit ausgefuehrt, weil sie rebuildbar sind oder keinen kritischen Datenbestand haben.

Q2 2026 - Konkrete Belegung

• Mini-Restore: Immich (erledigt 2026-05-27).
• DR-Sanity-Check (teilweise erledigt, Rest vor Quartalsende 2026-06-30):
  • Komodo-Bootstrap-Pfad: erledigt 2026-05-30 durch echten Trockenlauf via ops/restore-tests/komodo-bootstrap-test.sh --keep-data, Report /mnt/user/backups/restore-reports/komodo-bootstrap-2026-05-30.md, ops/komodo/docker-compose.yml als Recovery-Anker belegt.
  • Gitea-Bundles ueber ops/borg-ui/scripts/gitea-bundle-mirror.sh auf Frische und Bundle-Klonbarkeit pruefen: offen.
  • Secrets-Inventur gegen docs/SECRETS_MAP.md abgleichen: offen.

Wer schiebt das an?

• Operator loest jeden Drill manuell aus, idealerweise am 2. Wochenende des ersten Monats im Quartal.
• Es gibt keinen automatischen Host-Schedule fuer den Quartals-Drill. Die woechentliche Freshness-Pruefung und die monatlichen Mini-Restores in ops/restore-tests/schedule.md laufen separat.
• Bei akuten Aenderungen (Major-Upgrade eines Dienstes, FS-Migration, Repo-Strukturaenderung): zusaetzlichen Ad-hoc-Drill ausserhalb der Quartals-Kadenz einplanen.

Freshness-Check (woechentlich)

• Skript: ops/restore-tests/check-restore-freshness.sh (Host-Bash) bzw. ops/restore-tests/check-restore-freshness.ps1 (Windows-Operator).
• Erwartete Pruefungen:
  • Letzter Borg-Archiv-Stand juenger als die Schwellwerte aus docs/STORAGE_LAYOUT.md §11.
  • Kanonische Dump-Artefakte unter /mnt/user/backups/borg/dumps/latest/ vorhanden und juenger als 26 h.
  • Letzte Report-Dateien unter /mnt/user/backups/restore-reports/ lesbar.
  • Gitea-Bundles unter /mnt/user/backups/git-bundles/gitea/ plausibel aktuell.

Ergebnis ist ein kurzes Konsolen-Log; bei Fehler greift die ntfy-Alarmierung aus docs/ALERTING_MAP.md.

Mini-Restore (monatlich / bimonatlich)

Skripte folgen alle demselben Muster:

• isoliertes Test-Lab unter /mnt/user/backups/restore-lab/<dienst>
• isolierte Test-Container restoretest-*
• nur 127.0.0.1-Ports, keine Traefik-Labels, keine produktive Domain
• Smoke-Test mit Erfolgsregel "Container laeuft reicht nicht"
• Report unter /mnt/user/backups/restore-reports/<dienst>-YYYY-MM-DD.md

Operative Anleitungen je Dienst:

• ops/restore-tests/vaultwarden-runbook.md
• ops/restore-tests/gitea-runbook.md
• ops/restore-tests/paperless-runbook.md
• ops/restore-tests/immich-runbook.md

DR-Sanity-Check (quartalsweise)

Der Sanity-Check ist kein echter Restore. Er ist eine Doku-/Konsistenz-Pruefung mit zehn Punkten:

1. docs/DISASTER_RECOVERY.md Phase 1-5 noch konsistent mit Repo und Live-Stand?
2. docs/RESTORE_MATRIX.md Tier-Klassifizierung pro Dienst aktuell?
3. docs/SECRETS_MAP.md Pfade existieren, Stack-ENV-only-Liste aktuell?
4. docs/SERVICES_RECOVERY.md Komodo-Bootstrap-Pfad noch in Stufen A-F konsistent?
5. Gitea-Bundle-Mechanik laeuft und letzter Bundle-Stand klonbar (git clone .../homelab-infra.bundle /tmp/restore-test)?
6. Externe Mirrors (michaelkaleschke-spec/homelab-infra auf GitHub) gemaess docs/EXTERNAL_DEPENDENCIES.md noch erreichbar und aktuell?
7. ntfy-Push-Pfad noch erreichbar? (Test-Nachricht an homelab-info.)
8. Letzte vier Quartals-Mini-Restores im Report-Verzeichnis vorhanden?
9. Borg-Repo-Passphrase Offline-Sicherung noch auffindbar? (Pruefung durch Operator, nicht durch Skript, kein Wert ablegen.)
10. Capacity-Stand gegen Schwellen aus docs/CAPACITY_AND_LIFECYCLE.md abgeglichen?

Jeder Punkt wird in einem kurzen Quartals-Eintrag in docs/MIGRATION_LOG.md als ok / Abweichung / Folgeaufgabe festgehalten.

Abbruch-Regeln

Wenn ein Drill fehlschlaegt, gilt die Stop-Regel aus docs/WORKFLOW.md:

• nach zwei fehlgeschlagenen Reparaturversuchen nicht weiterschreiben
• stattdessen Pflichtmatrix aus docs/GITOPS_DRIFT_RUNBOOK.md durchgehen
• Befund dokumentieren, naechsten Schritt mit dem Operator klaeren
• erst danach den Drill erneut starten oder das Quartal als "Drill incomplete" markieren

Berichte

• Mini-Restore-Reports liegen unter /mnt/user/backups/restore-reports/<dienst>-YYYY-MM-DD.md.
• Quartals-Sanity-Checks landen als kurzer Block in docs/MIGRATION_LOG.md, nicht als eigenes Dokument.
• Reports werden nicht aus dem Repo verlinkt, weil sie nicht im Repo liegen. Operator dokumentiert nur Vorhanden/Erfolg/Datum.

Geltungsdauer

Diese Routine gilt ab Q2 2026. Bei groesseren Aenderungen (zweites Off-site, Authelia-OIDC-Aktivierung, Hardware-Migration) wird die Liste pro Quartal angepasst.