Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

docs(restore): finalize audit - handbook update, reifegrad matrix, backlog

Browse Source 
Schliesst das Restore-Skills-Audit 2026-06-02/03 ab:

- RESTORE_HANDBOOK.md auf Stand 2026-06-03: alle 6 verifizierten Tests
  (Vaultwarden, Gitea, Paperless, Immich, Authelia, Komodo-Bootstrap)
  dokumentiert, Frequenz-Tabelle aktualisiert, Betriebsmodus auf V1+
  (mit ntfy), Schnellstart um Immich/Authelia/Komodo ergaenzt,
  Report-Aufbewahrungsregel dokumentiert, Ausbaustufen priorisiert.

- RESTORE_MATRIX.md: neue Sektion "Restore-Test-Reifegrad" mit
  Uebersichtstabelle (pro Dienst: Tier, letzter Test, Typ, naechster
  Lauf) und priorisierter Kandidatenliste fuer fehlende Tests.

- Gitea-Restore: SSH-Check im Report korrekt als "TCP connect only"
  benannt statt "SSH port open" (war Audit-Finding M3).

- AUDIT_2026-05-25_TODO.md: Restore-Audit-Backlog ergaenzt mit den
  verbleibenden 8 offenen Punkten (Nextcloud, Shared PG18, Komodo-Mongo,
  Mailarchiver, Mealie, Traefik, Negativ-Test, E2E-DR-Drill).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Micha
2026-06-03 09:31:19 +02:00
parent ba3ef8fcfc
commit c922d1f241
4 changed files with 136 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AUDIT_2026-05-25_TODO.md
+15
View File
@@ -9,6 +9,21 @@ Audit-Snapshots wurden aus der Arbeitskopie entfernt; Detailhistorie liegt in Gi
|---|---|---|
| P2 | Family-Onboarding praktisch starten | Fokus: Vaultwarden als Passwortbasis, Immich-Mobile-Backup auf jedem Handy, Mealie mit erstem Rezept/Einkaufsliste; Ablauf steht in `docs/FAMILY_ONBOARDING.md` |
## Restore-Audit Backlog (Stand 2026-06-03)
Ergebnis des Restore-Skills-Audits (Session 2026-06-02/03). Die kritischen Bugfixes (Cron-OR-Semantik, ntfy-Race, Cleanup-Trap, Pfad-Inkonsistenz, Vaultwarden-Token, Paperless-Retry, Header-Validierung, Authelia-Test) sind erledigt und committed. Die folgenden Punkte sind bewusst offener Backlog:
| Prioritaet | Punkt | Status | Naechster Schritt |
|---|---|---|---|
| P1 | Nextcloud-Restore-Test | offen | Test nach Paperless-Muster, zusaetzlich `occ maintenance:mode`-Choreographie und `oc_admin`-Rolle. Hoechster Lerngewinn unter den fehlenden Tier-2-Tests |
| P1 | Shared PostgreSQL 18 Cluster Restore Drill | offen | Komplett-Drill: `pg_dumpall --globals-only` + per-DB Custom-Format-Dumps, inkl. `mailarchiver`-Bootstrap-Rollenkonflikt. Aktuell nur als Doku in RESTORE_MATRIX, kein automatischer Test |
| P1 | Komodo-Mongo-Daten-Restore | offen | Echtes `mongorestore --archive --gzip` von `komodo-mongo.archive.gz` in die Test-Mongo. Bootstrap-Compose-Test existiert, Daten-Replay nicht. Die Mongo-Dump ist die kanonische Quelle fuer `KOMODO_*`-Stack-ENVs wenn Vaultwarden gleichzeitig ausfaellt |
| P2 | Mailarchiver-Restore-Test | offen | Shared Postgres + Authelia-ForwardAuth; nach Nextcloud-Test |
| P2 | Mealie-Restore-Test | offen | Eigene Postgres + File-Restore |
| P2 | Traefik-Restore-Test | offen | Tier 1, aber komplex: `dynamic/` ist manuell-sync-Ausnahme, LE-State und CF-Token-Mount sind heikel |
| P3 | Negativ-Test fuer Frische-Check | offen | Einmal pro Quartal bewusst kaputten Dump einfuettern und pruefen ob `homelab-alerts` feuert |
| P3 | End-to-end-DR-Drill | offen | Komplett-Bootstrap Phase 1-5 auf einem Wegwerf-Host; realistisch nur mit zweiter Hardware |
## Bewusst geparkt
| Punkt | Entscheidung |
docs/RESTORE_HANDBOOK.md
+84 -40
View File
@@ -1,6 +1,6 @@
# Restore Handbook - KalliLab CORE
Stand: 2026-05-07
Stand: 2026-06-03
Dieses Handbuch ist die praktische Betriebsanleitung fuer Restore-Checks und Restore-Lab in KalliLab CORE.
@@ -41,28 +41,36 @@ Alle validierten Restore-Tests folgen demselben Muster:
### Vaultwarden
- Report: `/mnt/user/backups/restore-reports/vaultwarden-2026-05-07.md`
- Nachweis:
- Borg-Restore erfolgreich
- Testcontainer startete
- Login-Seite war erreichbar
- Erstlauf: 2026-05-07
- Nachweis: Borg-Restore, Testcontainer, Login-Seite erreichbar
### Gitea
- Report: `/mnt/user/backups/restore-reports/gitea-2026-05-07.md`
- Nachweis:
- Borg-Restore erfolgreich
- Web-UI antwortete
- SSH-Port reagierte
- Erstlauf: 2026-05-07
- Nachweis: Borg-Restore, Web-UI, SSH-TCP-Port
### 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
- Erstlauf: 2026-05-07, Folgelauf: 2026-05-31
- Nachweis: Borg-Datei-Restore, Dump-Import in Test-Postgres, Login-Seite, Doc-Count
### Immich
- Erstlauf: 2026-05-27
- Nachweis: DB-Dump-Restore in VectorChord-Test-Postgres, HTTP-Smoke, Asset-Count
- Hinweis: Foto-Dateien-Restore ist bewusst nicht Teil des Smokes
### Authelia
- Erstlauf: 2026-06-03
- Nachweis: Config-Borg-Restore, `authelia config validate`, HTTP-Health `/api/health`
- Hinweis: Daten-Restore des produktiven Dumps ist bewusst nicht Teil des Smokes (Storage-Encryption-Key-Kopplung)
### Komodo Bootstrap
- Erstlauf: 2026-05-30
- Nachweis: Compose-Validierung, Mongo healthy, Core HTTP, Periphery running
- Hinweis: Daten-Restore aus `komodo-mongo.archive.gz` ist noch nicht getestet
---
@@ -80,6 +88,10 @@ Alle validierten Restore-Tests folgen demselben Muster:
- `/mnt/user/backups/restore-lab/vaultwarden`
- `/mnt/user/backups/restore-lab/gitea`
- `/mnt/user/backups/restore-lab/paperless`
- `/mnt/user/backups/restore-lab/immich`
- `/mnt/user/backups/restore-lab/authelia`
- `/mnt/user/backups/restore-lab/komodo`
- `/mnt/user/backups/restore-lab/_failed` (Diagnose-Material bei Fehllaeufen)
### Reports
@@ -89,31 +101,33 @@ Alle validierten Restore-Tests folgen demselben Muster:
## 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
- jeden Montag, 06:30: Frische-Check fuer Dumps und Reports
- 1. Samstag im Monat, 07:00: Vaultwarden
- 3. Samstag im Monat, 07:15: Gitea
- 2. Samstag in ungeraden Monaten, 08:00: Paperless
- 2. Sonntag in Feb/Mai/Aug/Nov, 08:30: Immich
- 2. Samstag in geraden Monaten, 07:30: Authelia
- 1. Kalendertag im Monat, 09:00: Zufaelliger Restore aus Pool
Vollstaendiger Kalender mit Cron-Ausdruecken und Shell-Guards steht in `ops/restore-tests/schedule.md`.
---
## 6. Betriebsmodi
## 6. Betriebsmodus
### V1
Stand 2026-06-03 ist der Betrieb auf V1+ (V1 mit ntfy):
- 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
- validierte Bash-Host-Jobs fuer Vaultwarden, Gitea, Paperless, Immich, Authelia, Komodo-Bootstrap
- Host-Job-Definitionen und Cron-Vorlagen liegen im Repo (`ops/restore-tests/unraid-user-scripts.md`)
- `ntfy`-Wrapper sendet Erfolg an `homelab-info`, Fehler an `homelab-alerts`
- Frische-Check prueft zusaetzlich pg-Custom-Format-Dumps per `pg_restore --list` Header-Validierung
- bei Fehlschlag wird das Restore-Lab nach `_failed/` verschoben statt geloescht
### V2
Noch geplant fuer V2:
- `ntfy` bei Erfolg/Fehler
- Hermes liest Reports und baut Uebersichten
- zusaetzliche Rotation, Sammelreports und weitere Dienste
- Hermes-Zusammenfassung ueber vorhandene Reports
- Sammelreports und Report-Rotation
- weitere Dienste (Nextcloud, Mailarchiver, Mealie)
---
@@ -129,12 +143,15 @@ Host-Repo-Pfad:
/mnt/user/services/homelab-infra
```
V1-Jobs:
Jobs:
1. `restore-freshness-weekly`
2. `restore-vaultwarden-monthly`
3. `restore-gitea-monthly`
4. `restore-paperless-bimonthly`
5. `restore-immich-quarterly`
6. `restore-authelia-bimonthly`
7. `monthly-random-restore`
---
@@ -190,6 +207,24 @@ bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh gi
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh paperless
```
### Immich Restore-Check
```bash
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh immich
```
### Authelia Restore-Check
```bash
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh authelia
```
### Komodo Bootstrap Trockenlauf
```bash
bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-checks.sh komodo-bootstrap
```
### Optional mit `ntfy`
```bash
@@ -200,7 +235,16 @@ bash /mnt/user/services/homelab-infra/ops/restore-tests/run-restore-job-with-ntf
## 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`
1. Nextcloud-Restore-Test (mit `occ maintenance:mode`-Choreographie)
2. Mailarchiver-Restore-Test
3. Mealie-Restore-Test
4. Komodo-Mongo-Daten-Restore (echtes `mongorestore` statt reinem Bootstrap)
5. Shared-PostgreSQL-18-Cluster-Restore-Drill (globals + per-DB-Dumps)
6. Traefik-Restore-Test (mit `dynamic/` und LE-State)
7. Hermes-Zusammenfassung ueber vorhandene Reports
8. Report-Rotation (archivieren nach 12 Monaten)
9. Negativ-Test: bewusst kaputten Dump in den Frische-Check einfuettern
## 12. Report-Aufbewahrung
Reports unter `/mnt/user/backups/restore-reports` werden dauerhaft aufbewahrt. Bei wachsender Anzahl (ca. 50-60 pro Jahr) empfiehlt sich eine jaehrliche Archivierung alter Reports in einen Unterordner `_archive/YYYY/`. Der Frische-Check warnt bei `MAX_REPORT_AGE_DAYS=45`, loescht aber bewusst nicht automatisch.
docs/RESTORE_MATRIX.md
+34 -7
View File
@@ -125,13 +125,40 @@ Die Dump-Erzeugung ist host-seitig ueber `ops/borg-ui/scripts/pre-backup-dumps.s
---
## Erste sinnvolle Referenz-Restores
## Restore-Test-Reifegrad
Wenn weitere Restore-Uebungen dokumentiert werden sollen, sind diese Dienste besonders geeignet:
Stand 2026-06-03. Pro Dienst auf einen Blick: Wurde der Restore schon einmal real getestet?
1. `mail-archiver`
2. `paperless-ngx`
3. `gitea`
4. `vaultwarden`
| Dienst | Tier | Letzter Restore-Test | Typ | Naechster Lauf |
|---|---|---|---|---|
| Vaultwarden | 1 | 2026-05-07 | File + Container + HTTP | monatlich (1. Sa) |
| Gitea | 1 | 2026-05-07 | File + Container + HTTP + TCP | monatlich (3. Sa) |
| Authelia | 1 | 2026-06-03 | Config + Validate + HTTP Health | zweimonatlich (2. Sa gerade Mon.) |
| Komodo Bootstrap | 1 | 2026-05-30 | Compose + Mongo + HTTP | quartalsweise |
| Paperless | 2 | 2026-05-31 | File + Dump + Container + HTTP + Doc-Count | zweimonatlich (2. Sa ungerade Mon.) |
| Immich | 2 | 2026-05-27 | Dump + Container + HTTP + Asset-Count | quartalsweise (2. So Feb/Mai/Aug/Nov) |
| Unraid OS Flash | 1 | - | noch kein Test | - |
| Traefik | 1 | - | noch kein Test | naechster Kandidat |
| AdGuard Home | 1 | - | noch kein Test | - |
| Tailscale | 1 | - | noch kein Test | - |
| PostgreSQL 18 Cluster | 1 | - | noch kein Test (globals + per-DB) | naechster Kandidat |
| Redis 8 | 1 | - | noch kein Test | - |
| Komodo Mongo Daten | 1 | - | noch kein Test (mongorestore) | naechster Kandidat |
| Nextcloud | 2 | - | noch kein Test | **hoechste Prio** (occ-Choreographie) |
| Mealie | 2 | - | noch kein Test | - |
| Mail-Archiver | 2 | - | noch kein Test | - |
| Glance | 2 | - | rebuildbar, kein Test noetig | - |
| ntfy | 2 | - | rebuildbar, kein Test noetig | - |
| Borg UI | 3 | - | rebuildbar | - |
| Filebrowser | 3 | - | rebuildbar | - |
Sie liefern hohen Erkenntnisgewinn ohne den kompletten Homelab-Neuaufbau zu brauchen.
---
## Naechste Restore-Test-Kandidaten (priorisiert)
1. **Nextcloud** - hoechste Prio wegen `occ maintenance:mode`-Choreographie und `oc_admin`-Rolle
2. **Shared PostgreSQL 18 Cluster** - globals + per-DB-Dumps, Bootstrap-Konflikt `mailarchiver`
3. **Komodo Mongo Daten** - echtes `mongorestore` aus `komodo-mongo.archive.gz` (Quelle fuer `KOMODO_*`-Stack-ENVs im DR)
4. **Mailarchiver** - Tier 2, shared Postgres + Authelia ForwardAuth
5. **Mealie** - Tier 2, eigene Postgres
6. **Traefik** - Tier 1, aber komplex (dynamic/, LE-State, CF-Token-Mount)
ops/restore-tests/gitea-restore-test.sh
+3 -3
View File
@@ -67,9 +67,9 @@ sleep 8
status="$(curl -s -o /tmp/gitea-body.html -w '%{http_code}' http://127.0.0.1:13000)"
grep -qi "Gitea" /tmp/gitea-body.html
if timeout 5 bash -lc '</dev/tcp/127.0.0.1/12222' >/dev/null 2>&1; then
ssh_state="open"
ssh_state="tcp-open"
else
echo "Gitea SSH port not reachable" >&2
echo "Gitea SSH port not reachable (TCP connect failed)" >&2
exit 1
fi
@@ -91,7 +91,7 @@ write_report "$REPORT_FILE" <<EOF
- Borg extract into isolated restore-lab: \`ok\`
- HTTP status: \`$status\`
- HTML content: \`Gitea\`
- SSH port: \`$ssh_state\`
- SSH TCP port: \`$ssh_state\` (TCP connect only, not a full SSH handshake)
- Repository sample: \`$repo_sample\`
## Notes