Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
43727151dfb553852f7b45c9d71054ef70444dbd
homelab-infra/docs/DISASTER_RECOVERY.md
T
Micha cd650b19ac Close Gitea signup, dedup posture-check alerts, extend Borg scope 
Operational hardening across several services after live incident
analysis between 2026-05-18 and 2026-05-20:

- Gitea: disable public registration and OpenID signup/signin to
  stop the external POST / 5xx bursts that triggered availability
  alerts. New repo-wide policy requires every productive
  Micha/homelab-infra Komodo stack to ship with an active
  Gitea->Komodo webhook on the current stack ID (documented in
  CLAUDE.md, AI_CONTEXT.md, WORKFLOW.md).
- posture-check: extract the Disk1 fstype check into its own
  function so the documented Disk1 NTFS exception no longer raises
  ntfy warnings, skip POSIX inode checks on NTFS, and dedup ntfy
  alerts via a fingerprint state file with ALERT_REPEAT_SECONDS
  (default 24h). Repeat-spam on the same cause now suppressed.
- docker-critical-events: parse the event JSON for container name,
  action, exit code and signal; drop `die exit=0` events (clean
  stops); ship a structured ntfy message instead of the raw event
  line.
- Borg UI: mount /mnt/user/services into the backup container as
  /local/services:ro and include homelab-infra, stacks and
  posture-check in all-important-sources.txt. RESTORE_MATRIX and
  DISASTER_RECOVERY updated accordingly.
- Unraid user scripts: document the new
  homelab-operations-report-daily cron job and the SMTP password
  file it expects on the host.
- MIGRATION_LOG: capture the four live events from this window -
  Gitea 5xx burst + signup closure, Komodo webhook reconciliation,
  posture-check host-version verification, Borg scope extension,
  and Traefik 5xx alert detuning.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 11:05:35 +02:00

416 lines
11 KiB
Markdown
Raw Blame History

# Disaster Recovery - KalliLab CORE
Dieses Dokument beschreibt den **kontrollierten Wiederanlauf nach einem Totalausfall des Unraid-Hosts**.
Es ist bewusst **repo-genau** fuer dieses Homelab geschrieben und ersetzt keine Backup-Dokumentation im engeren Sinn.
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
---
## 1. Ziel und Geltungsbereich
Dieses Runbook behandelt primaer den Fall:
- Unraid-Host war ausgefallen oder musste neu aufgesetzt werden
- Array / Shares sind wieder verfuegbar
- Daten auf den Festplatten sind grundsaetzlich noch lesbar oder koennen aus Borg wiederhergestellt werden
Es behandelt **nicht** im Detail:
- den Rueckweg einzelner Fehl-Deployments im laufenden Betrieb
- eine spontane Live-Reparatur an einem einzelnen Service
- einen kompletten Datenverlust ohne verfuegbares Borg- oder Share-Material
---
## 2. Zwei verschiedene Ernstfaelle
Diese beiden Szenarien muessen sauber getrennt werden:
### A. Host-/Systemausfall, aber Daten auf den Shares sind noch da
Das ist der wahrscheinlichere und einfachere Fall.
Dann muessen in vielen Bereichen **keine Daten aus Borg extrahiert** werden. Es reicht oft:
1. Unraid sauber neu aufzusetzen
2. Shares wieder einzubinden
3. Repo / Secrets / Laufzeitpfade zu pruefen
4. Stacks in der richtigen Reihenfolge wieder hochzufahren
### B. Daten muessen wirklich aus Borg wiederhergestellt werden
Das ist der schwerere Fall.
Dann muessen gezielt die in `docs/RESTORE_MATRIX.md` beschriebenen Pfade, Dumps und Secrets aus Borg oder anderen Restore-Quellen zurueckgeholt werden.
**Merksatz:** Erst klaeren, ob wir nur den Host wiederbeleben oder echte Nutz-/App-Daten aus Backups zurueckholen muessen.
---
## 3. Voraussetzungen vor einem Ernstfall
Diese Punkte sollten **vor** einem echten Ausfall geklaert sein:
| Thema | Sollzustand |
|---|---|
| Repo-Zugang ausserhalb von Gitea | externer Mirror oder lokaler aktueller Clone vorhanden |
| Unraid USB-/Flash-Backup | eingerichtet und wiederherstellbar |
| Borg-Ziel | nicht nur lokal auf demselben Ausfallpfad |
| Borg-Passphrase | extern sicher hinterlegt |
| Secrets-Dateien | ueber Borg bzw. Restore-Quellen abgedeckt |
| Komodo Stack ENV-Werte | extern dokumentiert, z. B. Vaultwarden |
| Restore-Smoke-Tests | fuer mindestens 1-2 kritische Dienste nachgewiesen |
**Wichtig:** Dieses Dokument ist nur so gut wie die Vorbereitung ausserhalb des Repos.
---
## 4. Phase 0 - Repo-Zugang sicherstellen
Nach einem Totalausfall kann es sein, dass `gitea` selbst noch nicht laeuft.
Deshalb gilt:
1. Wenn moeglich, Repo ueber einen externen Mirror oder einen lokalen aktuellen Clone holen.
2. Nur wenn `gitea` bereits wieder verfuegbar ist, direkt aus `git.kaleschke.info` klonen.
Empfohlene Wege:
- externer Push-Mirror
- lokaler Bare-Clone auf dem PC
- normaler lokaler Arbeits-Clone auf dem PC
Wenn **kein externer Repo-Zugang** besteht, ist `services/gitea/data` selbst ein kritischer Restore-Pfad.
---
## 5. Phase 1 - Unraid und Shares wiederherstellen
### 5.1 Unraid-Grundzustand
1. Unraid USB/Flash wiederherstellen oder neu aufsetzen
2. Lizenz / Device-Zuordnung sauber herstellen
3. Array wieder zuweisen und starten
4. Grundlegende Shares pruefen
### 5.2 Erwartete Shares / Pfade
Mindestens diese Pfade muessen wieder verfuegbar sein:
- `/mnt/user/appdata`
- `/mnt/user/backups`
- `/mnt/user/services`
- `/mnt/user/documents`
- `/mnt/user/photos`
Je nach Dienst zusaetzlich:
- `/mnt/user/finance`
- `/mnt/remotes/...` fuer externe Backup-Ziele
Wenn diese Pfade **nicht** sauber da sind, keine Stacks starten.
---
## 6. Phase 2 - Secrets und kritische Restore-Pfade pruefen
Bevor produktive Dienste hochfahren, muessen die wichtigsten Secret- und Konfigurationspfade verifiziert werden.
### 6.1 Zentrale Secrets
Erwartete Basis unter `/mnt/user/appdata/secrets/`:
- `authelia_jwt_secret.txt`
- `authelia_postgres_password.txt`
- `authelia_session_secret.txt`
- `authelia_smtp_password.txt`
- `authelia_storage_encryption_key.txt`
- `immich_postgres_password.txt`
- `komodo_mongo_password.txt`
- `mealie_postgres_password.txt`
- `nextcloud_admin_password.txt`
- `nextcloud_admin_user.txt`
- `nextcloud_postgres_password.txt`
- `postgres_password.txt`
- `redis_password.txt`
- `borg_repo_passphrase.txt`
- `vaultwarden_admin_token.txt`
- `hermes_runner_id_ed25519`
Weitere relevante Secret-Pfade:
- `/mnt/user/appdata/traefik/secrets/cloudflare_dns_api_token`
- `/mnt/user/appdata/code-server/secrets/password`
### 6.2 Stack-ENV-Werte ausserhalb von Datei-Secrets
Diese Werte sind vor dem Start der betroffenen Dienste zu pruefen bzw. wieder in Komodo zu hinterlegen:
- `PAPERLESS_DBPASS`
- `PAPERLESS_REDIS`
- `IMMICH_DB_PASSWORD`
- `MAILARCHIVER_DB_CONNECTION`
- `MAILARCHIVER_AUTH_PASSWORD`
- `HERMES_DASHBOARD_HOST`
- Hermes Host-`.env` fuer Provider-/API-/Home-Assistant-Tokens
- `KOMODO_SECRET_KEY`
- `KOMODO_WEBHOOK_SECRET`
- `KOMODO_JWT_SECRET`
- `KOMODO_MONGO_PASSWORD`
- `KOMODO_PERIPHERY_PASSKEY`
- relevante `HOMEPAGE_VAR_*`
- `APP_KEY` und `ADMIN_PASSWORD` fuer `speedtest-tracker`
### 6.3 Rechte
Nach einem Restore oder manuellem Rueckkopieren:
- Secret-Dateien wieder auf sinnvolle restriktive Rechte setzen
- keine produktiven Dienste starten, solange offensichtliche Secret-Dateien fehlen
---
## 7. Phase 3 - Was wirklich aus Borg kommen muss
Nicht alles muss in jedem Fall aus Borg zurueckgespielt werden.
### 7.1 Typischer Host-Ausfall ohne Datenverlust
In diesem Fall meist **kein kompletter Borg-Extract** notwendig.
Stattdessen:
1. Shares und Pfade pruefen
2. Secrets pruefen
3. Dumps unter `/mnt/user/backups/borg/dumps/latest` pruefen
4. Stacks kontrolliert hochfahren
### 7.2 Wenn echte Daten aus Borg benoetigt werden
Dann nur gezielt die in `docs/RESTORE_MATRIX.md` beschriebenen Pfade wiederherstellen.
Besonders kritisch:
- `/mnt/user/appdata/secrets`
- `/mnt/user/appdata/traefik`
- `/mnt/user/services/homelab-infra`
- `/mnt/user/services/stacks`
- `/mnt/user/services/posture-check`
- `/mnt/user/services/gitea/data`
- `/mnt/user/appdata/authelia/config`
- `/mnt/user/appdata/komodo/core`
- `/mnt/user/appdata/komodo/periphery`
- `/mnt/user/backups/borg/dumps/latest`
- dienstspezifische App- und Nutzdatenpfade
**Nicht blind alles extrahieren**, wenn nur einzelne Pfade oder Dienste betroffen sind.
---
## 8. Phase 4 - Bootstrap-Reihenfolge der Stacks
**Nie alle Stacks gleichzeitig starten.**
### Stufe 1 - Netz und Zugang
1. `traefik/`
2. `host-services/Adguard/`
3. `host-services/tailscale/`
Ziel:
- Web-Einstieg funktioniert
- DNS/Resolver-Basis ist da
- Remote-Zugang ist wieder verfuegbar
### Stufe 2 - Gemeinsame Backends und Identity
4. `infra/postgresql17/`
5. `security/authelia/`
6. `infra/redis/`
7. `core/gitea/`
Ziel:
- gemeinsame DB verfuegbar
- zentrale Auth laeuft; Authelia nutzt bewusst kein Redis-Session-Backend
- Authelia SMTP-Notifier kann GMX erreichen
- Redis als shared Cache fuer abhaengige Apps verfuegbar
- Git-Zugriff wiederhergestellt
### Stufe 3 - Deploy-System
8. `ops/komodo/`
Ziel:
- Komodo Core und Mongo laufen
- Periphery verbindet sich wieder
- Stacks koennen wieder aus Git konsumiert werden
### Stufe 4 - Kritische Anwendungen
9. `security/vaultwarden/`
10. `apps/paperless/`
11. `apps/immich/`
12. `apps/mealie/`
13. `apps/mail-archiver/`
14. `apps/nextcloud/`
### Stufe 5 - Restliche Apps und Ops
15. `apps/homepage/`
16. `apps/ntfy/`
17. `apps/paperless-gpt/`
18. `apps/bentopdf/`
19. `ops/uptime-kuma/`
20. `ops/borg-ui/`
21. `ops/filebrowser/`
22. `ops/glances/`
23. `ops/scrutiny/`
24. `ops/speedtest/`
25. `monitoring/`
26. `ops/hermes-agent/`
27. `infra/ddns-updater/`
**Regel:** Nach jeder Stufe kurz pruefen, bevor die naechste beginnt.
---
## 9. Phase 5 - Verifikation nach dem Wiederanlauf
### 9.1 Fundament
- `traefik.kaleschke.info` erreichbar
- Authelia-Login funktioniert
- AdGuard beantwortet DNS-Anfragen
- Tailscale ist verbunden
### 9.2 GitOps
- `git.kaleschke.info` erreichbar
- Repo vorhanden
- `komodo.kaleschke.info` erreichbar
- Periphery verbunden
### 9.3 Kritische Apps
- Vaultwarden startet und ist erreichbar
- Paperless startet und sieht Dokumente
- Immich startet und sieht Medien
- Mealie startet
- Mail-Archiver startet
- Nextcloud startet und sieht Dateien
### 9.4 Backup-/Beobachtungsebene
- Borg UI startet und kennt sein Repo noch
- aktuelle Dump-Artefakte sind vorhanden
- Uptime Kuma / Homepage / ntfy sind wieder da
- Hermes Gateway und Dashboard starten; `hermes.kaleschke.info` leitet anonym zu Authelia weiter
---
## 10. Bekannte Sonderregeln
### Traefik `dynamic/`
`traefik/dynamic/*` bleibt eine dokumentierte manuelle Ausnahme.
Das bedeutet:
- Git allein reicht hier nicht
- die Dateien unter `/mnt/user/appdata/traefik/dynamic/` muessen real vorhanden sein
- nach einem Restore oder Neuaufbau diesen Pfad explizit pruefen
### `paperless-ngx`
`paperless-ngx` bleibt bewusst bei Stack Environment Variables fuer:
- `PAPERLESS_DBPASS`
- `PAPERLESS_REDIS`
Nach einem Komodo-Neuaufbau muessen diese Werte vor dem Start des Stacks wieder gesetzt sein.
### `authelia`
Authelia nutzt GMX SMTP fuer Identity-/2FA-Benachrichtigungen.
Vor dem Start muessen vorhanden sein:
- `/mnt/user/appdata/secrets/authelia_smtp_password.txt`
- SMTP-Zugang fuer `michideheld@gmx.de`
Beim Smoke-Test muss `authelia validate-config` erfolgreich sein; der SMTP-Startup-Check darf den Start nicht blockieren.
### `nextcloud`
`nextcloud` ist bewusst kein AIO-Stack, sondern ein klassischer App-/PostgreSQL-/Redis-Stack.
Vor dem Start muessen vorhanden sein:
- `/mnt/user/appdata/secrets/nextcloud_admin_user.txt`
- `/mnt/user/appdata/secrets/nextcloud_admin_password.txt`
- `/mnt/user/appdata/secrets/nextcloud_postgres_password.txt`
Zusaetzlich muss der Nutzdatenpfad `/mnt/user/documents/nextcloud-data` erreichbar sein.
### Borg-Dumps
Die Dump-Erzeugung ist host-seitig gedacht, nicht als Borg-UI-Inline-Hook.
Relevant:
- Dump-Ziel: `/mnt/user/backups/borg/dumps/latest`
- Skript: `ops/borg-ui/scripts/pre-backup-dumps.sh`
### Hermes Agent
Hermes nutzt einen lokalen Build und hostseitige Runtime-Daten.
Vor dem Start muessen vorhanden sein:
- `/mnt/user/appdata/hermes-agent/data`
- `/mnt/user/appdata/hermes-agent/ssh`
- `/mnt/user/appdata/secrets/hermes_runner_id_ed25519`
- die hostseitige Hermes `.env` mit Provider-/API-/Home-Assistant-Tokens
Smoke-Test: `hermes-gateway` healthcheck ist gruen, `hermes.kaleschke.info` leitet fuer anonyme Requests zu Authelia weiter.
### Gitea
Wenn weder externer Mirror noch lokaler Clone verfuegbar sind, ist `services/gitea/data` selbst Teil des kritischen Wiederanlaufs.
---
## 11. Offene Vorbereitungs-To-dos
- externer Repo-Zugang fuer den Ernstfall absichern
- Unraid-USB-/Flash-Backup pruefen
- Borg-Passphrase extern sicher hinterlegen
- Komodo Stack-ENV-Werte zentral ausserhalb von Komodo dokumentieren
- regelmaessige automatisierte Restore-Smoke-Tests fuer Vaultwarden, Gitea und Paperless etablieren
- `komodo-mongo`-Dump nach Major-Upgrades gezielt kontrollieren
---
## 12. Kurzform fuer den Ernstfall
Wenn es schnell gehen muss:
1. Unraid und Shares sauber wiederherstellen
2. Repo-Zugang sichern
3. Secrets und Stack-ENV-Werte pruefen
4. Stacks in der festgelegten Reihenfolge hochfahren
5. Kritische Apps testen
6. Nur bei echtem Datenbedarf gezielt aus Borg wiederherstellen
Dieses Dokument soll **Ruhe in den Ablauf bringen**, nicht Hektik erzeugen.
Reference in New Issue View Git Blame Copy Permalink