homelab-infra/ops/restore-tests/README.md

# Restore-Tests - Betrieb und Werkzeuge

Typ: Runbook/Tool-Doku · Stand: 2026-06-11 · Status: aktiv

Kontrollierte Restore-Tests fuer `homelab-infra`. Dieses Dokument ist das
**einzige** Betriebsdokument fuer Restore-Tests (das fruehere
`docs/RESTORE_HANDBOOK.md` ist hierin aufgegangen). Verwandt:

- `docs/RESTORE_MATRIX.md` - Restore-Quellen, Secrets, Smoke-Tests und **Test-Reifegrad je Dienst** (einziger Status-Ort)
- `docs/DISASTER_RECOVERY.md` - echter Wiederanlauf
- `schedule.md` - Kadenz, Cron-Ausdruecke und Shell-Guards
- `unraid-user-scripts.md` - Unraid-User-Script-Vorlagen fuer die Host-Jobs

## Grundregeln

- Restore-Quelle bleibt das produktive Borg-Repo bei Hetzner; Zugriff ueber den vorhandenen `borg-ui`-Container
- Passphrase kommt aus `/mnt/user/appdata/secrets/borg_repo_passphrase.txt`, nie aus UI-Interna
- Testdaten landen nur unter `/mnt/user/backups/restore-lab/<dienst>`; bei Fehlschlag wird nach `_failed/` verschoben statt geloescht
- Reports landen unter `/mnt/user/backups/restore-reports`
- Testcontainer nutzen das Praefix `restoretest-`, localhost-Ports, keine produktive Domain, keine Traefik-Route
- keine produktiven Volumes schreibend mounten, keine produktiven Pfade beschreiben
- keine Restore-Automatik fuer neue Dienste ohne bewusste Freigabe

## Erfolgskriterien

Ein Restore-Test gilt nur dann als erfolgreich, wenn Quelle lesbar war, Daten
im Restore-Lab ankamen, der Testcontainer startete, der **fachliche**
Smoke-Test gelang und ein Report geschrieben wurde. "Container laeuft" allein
reicht nicht.

## Aufbau des Verzeichnisses

Pro Dienst existieren bis zu drei Artefakte:

- `<dienst>-restore-test.sh` - automatisierter Host-Job (produktive Wahrheit)
- `<dienst>-compose.test.yml` - isolierte Testinstanz
- `<dienst>-runbook.md` - manueller Ablauf bzw. Besonderheiten

Dazu zentrale Helfer:

- `run-restore-checks.sh` - Dispatcher (Host), `run-restore-checks.ps1` (lokale Planvariante)
- `run-restore-job-with-ntfy.sh` - Wrapper: Erfolg -> `homelab-info`, Fehler -> `homelab-alerts`
- `check-restore-freshness.sh` / `.ps1` - woechentlicher Frische-Check fuer Dumps und Reports (prueft pg-Dumps per `pg_restore --list`)
- `negative-freshness-alert-test.sh` - sicherer Negativtest des Alarmwegs (synthetischer Leerpfad, quartalsweise)
- `common.sh` - gemeinsame Borg-/Compose-Helfer
- `automation-plan.md` - Host-Job- und Automatisierungsmodell

## Betriebsmodus

Stand 2026-06-11 ist der Betrieb auf V1+ (validierte Bash-Host-Jobs mit ntfy):

- Host-Jobs laufen als Unraid User Scripts vom Repo-Spiegel `/mnt/user/services/homelab-infra`
- Kadenz und Cron-Ausdruecke: `schedule.md` (woechentlicher Frische-Check, monatliche/quartalsweise Dienst-Rotation, monatlicher Zufalls-Restore)
- Job-Vorlagen: `unraid-user-scripts.md`

## Schnellstart

```bash
# Frische-Check
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh freshness

# Dienst-Restore-Check (vaultwarden|gitea|paperless|immich|authelia|adguard|redis|homeassistant|komodo-bootstrap|nextcloud|hetzner-snapshot)
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh <dienst>

# Negativtest des Alarmwegs (quartalsweise)
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh freshness-negative

# Mit ntfy-Meldung
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-job-with-ntfy.sh freshness homelab-info
```

## Status je Dienst

Einziger Status-Ort ist die **Reifegrad-Tabelle** in `docs/RESTORE_MATRIX.md`
(letzter Test, Typ, naechster Lauf). Hier nur Besonderheiten:

- **Nextcloud:** Test am 2026-06-03 erfolgreich, aber mit Unraid-shfs-Eigenheit: Nextcloud fuehrt `chmod()` unter `/var/www/html` aus, was auf FUSE/shfs scheitert. Das Skript patcht `check_data_directory_permissions: false` und legt den `.ncdata`-Marker an.
- **Authelia:** bewusst Config-Smoke ohne produktiven Dump-Restore (Storage-Encryption-Key-Kopplung).
- **Immich:** Foto-Dateien-Restore ist bewusst nicht Teil des Smokes (separater DR-Drill); Test-Postgres nutzt das produktive VectorChord-Image.
- **Home Assistant:** nutzt das neueste HA-native Backup-Artefakt und eine Kopie der Mosquitto-Appdata; Testcontainer laufen nur auf localhost-Ports, ohne Traefik/Public Route.
- **Unraid-Flash / Tailscale:** noch ohne vollstaendigen Erstlauf - `unraid-flash-runbook.md`, `tailscale-runbook.md`; offene Schritte in `docs/MASTER_TODO.md`.
- **Hetzner-Snapshot:** Infrastruktur-Test (kein Service-Restore): prueft `.zfs/snapshot` der Storage Box (Existenz, Retention, Einzeldatei-Restore) und belegt den snapshot-basierten Off-site-Schutz. Dispatcher `hetzner-snapshot`, Runbook `hetzner-snapshot-runbook.md`. Live validiert 2026-06-23 (7 Snapshots, Einzeldatei-Restore ok); monatlich im `schedule.md`.

## Naechste Ausbaustufen

1. Hermes-Zusammenfassung ueber vorhandene Reports (geparkt mit Hermes)
2. Report-Rotation: Reports werden dauerhaft aufbewahrt; bei wachsender Anzahl jaehrlich nach `_archive/YYYY/` verschieben. Der Frische-Check warnt ab `MAX_REPORT_AGE_DAYS=45`, loescht aber nie automatisch.