From d20b68721111023c1fccde07035104de8f83b161 Mon Sep 17 00:00:00 2001 From: Micha Date: Thu, 7 May 2026 11:11:36 +0200 Subject: [PATCH] Add restore handbook and Unraid job guide --- docs/DISASTER_RECOVERY.md | 1 + docs/RESTORE_HANDBOOK.md | 200 +++++++++++++++++++++++ ops/restore-tests/unraid-user-scripts.md | 106 ++++++++++++ 3 files changed, 307 insertions(+) create mode 100644 docs/RESTORE_HANDBOOK.md create mode 100644 ops/restore-tests/unraid-user-scripts.md diff --git a/docs/DISASTER_RECOVERY.md b/docs/DISASTER_RECOVERY.md index 4c40180..863f548 100644 --- a/docs/DISASTER_RECOVERY.md +++ b/docs/DISASTER_RECOVERY.md @@ -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 --- diff --git a/docs/RESTORE_HANDBOOK.md b/docs/RESTORE_HANDBOOK.md new file mode 100644 index 0000000..f641c0a --- /dev/null +++ b/docs/RESTORE_HANDBOOK.md @@ -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/` +- 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` diff --git a/ops/restore-tests/unraid-user-scripts.md b/ops/restore-tests/unraid-user-scripts.md new file mode 100644 index 0000000..35360fa --- /dev/null +++ b/ops/restore-tests/unraid-user-scripts.md @@ -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 +```