Add restore handbook and Unraid job guide

2026-05-07 11:11:36 +02:00
parent 16416d964f
commit d20b687211
3 changed files with 307 additions and 0 deletions
@@ -8,6 +8,7 @@ Verwandte Dokumente:

 - `docs/ROLLBACK.md` - Rueckweg bei Fehlern im laufenden GitOps-Betrieb
 - `docs/RESTORE_MATRIX.md` - Restore-Quellen und Verifikationsregeln pro Dienst
+- `docs/RESTORE_HANDBOOK.md` - praktische Restore-Betriebsanleitung
 - `ops/borg-ui/BACKUP_SCOPE.md` - Zielbild des Borg-Scopes

 ---
@@ -0,0 +1,200 @@
+# 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
+
+- manuell validierte Restore-Pfade
+- Host-Job-Definitionen liegen im Repo
+- Scheduler kann bereits Plan- und Frische-Checks fahren
+- volle Automatik je Dienst wird danach gezielt nachgezogen
+
+### V2
+
+- echte Vollautomatik fuer die drei validierten Dienste
+- `ntfy` bei Erfolg/Fehler
+- Hermes liest spaeter Reports und baut Uebersichten
+
+---
+
+## 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
+```
+
+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
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode freshness
+```
+
+### Vaultwarden Planlauf
+
+```bash
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode vaultwarden -WhatIf
+```
+
+### Gitea Planlauf
+
+```bash
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode gitea -WhatIf
+```
+
+### Paperless Planlauf
+
+```bash
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode paperless -WhatIf
+```
+
+---
+
+## 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`
@@ -0,0 +1,106 @@
+# Unraid User Scripts fuer Restore-Checks
+
+## Ziel
+
+Diese Vorlagen binden die validierten Restore-Checks in Unraid User Scripts ein.
+
+Host-Repo-Pfad:
+
+```text
+/mnt/user/services/homelab
+```
+
+## Script 1 - `restore-freshness-weekly`
+
+Zeit:
+
+- Montag, 06:30
+
+Inhalt:
+
+```bash
+#!/bin/bash
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode freshness \
+  > /mnt/user/backups/restore-reports/freshness-$(date +%F).md
+```
+
+Erwartung:
+
+- prueft Dump-Frische
+- prueft Report-Frische
+- startet keine Container
+
+## Script 2 - `restore-vaultwarden-monthly`
+
+Zeit:
+
+- 1. Samstag im Monat, 07:00
+
+V1-Inhalt:
+
+```bash
+#!/bin/bash
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode vaultwarden -WhatIf \
+  > /mnt/user/backups/restore-reports/vaultwarden-plan-$(date +%F).md
+```
+
+## Script 3 - `restore-gitea-monthly`
+
+Zeit:
+
+- 3. Samstag im Monat, 07:00
+
+V1-Inhalt:
+
+```bash
+#!/bin/bash
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode gitea -WhatIf \
+  > /mnt/user/backups/restore-reports/gitea-plan-$(date +%F).md
+```
+
+## Script 4 - `restore-paperless-bimonthly`
+
+Zeit:
+
+- jeder 2. Monat, 2. Samstag, 08:00
+
+V1-Inhalt:
+
+```bash
+#!/bin/bash
+pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode paperless -WhatIf \
+  > /mnt/user/backups/restore-reports/paperless-plan-$(date +%F).md
+```
+
+## Warum V1 mit `-WhatIf`
+
+- keine unkontrollierten Restore-Laeufe im Cron
+- erst Host-Scheduler sauber verdrahten
+- spaeter gezielt auf echte Vollautomatik umstellen
+
+## V2 Zielbild
+
+Spaeter werden die drei Restore-Scripts von Plan-/Scaffold-Modus auf echte Host-Ausfuehrung umgestellt:
+
+1. Restore aus Borg
+2. Testcontainer starten
+3. Smoke-Test
+4. Report schreiben
+5. optional `ntfy`
+6. Bereinigung
+
+## Optionales `ntfy` Wrapper-Muster
+
+Wenn `ntfy` spaeter dazukommt, soll der Host-Job nur Erfolg/Fehler referenzieren, nicht den ganzen Report in die Nachricht kippen.
+
+Beispiel:
+
+```bash
+#!/bin/bash
+REPORT="/mnt/user/backups/restore-reports/freshness-$(date +%F).md"
+if pwsh -File /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.ps1 -Mode freshness > "$REPORT"; then
+  echo "Restore freshness check ok: $REPORT"
+else
+  echo "Restore freshness check failed: $REPORT"
+fi
+```