homelab-infra/docs/DISASTER_RECOVERY.md

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
• docs/SERVICES_RECOVERY.md - Recovery-kritische /mnt/user/services-Pfade, Gitea-Mirror und Komodo-Bootstrap
• docs/EXTERNAL_DEPENDENCIES.md - externe Provider/Konten und Ausfall-Szenarien
• 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	privater GitHub-Push-Mirror michaelkaleschke-spec/homelab-infra und lokaler aktueller Clone vorhanden
Unraid USB-/Flash-Backup	unraid-flash-config.tar.gz wird vor Borg unter /mnt/user/backups/borg/dumps/latest erzeugt und nach Hetzner/Borg gesichert; Unraid-Connect-Cloud-Backup optional zusaetzlich
Borg-Ziel	nicht nur lokal auf demselben Ausfallpfad
Borg-Passphrase	Host-Secret-Datei vorhanden und fuer Borg-Zugriff verifiziert; externe Offline-Hinterlegung vom Operator am 2026-05-26 bestaetigt
Secrets-Dateien	ueber Borg bzw. Restore-Quellen abgedeckt
Komodo Stack ENV-Werte	extern dokumentiert, z. B. Vaultwarden
Services-Recovery	docs/SERVICES_RECOVERY.md gepflegt, insbesondere Gitea-Repo-Mirror und Komodo-Bootstrap
Hardware-/Netzwerkdaten	docs/HARDWARE_INVENTORY.md und docs/NETWORK_INVENTORY.md mit echten Werten gefuellt
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.

Verfuegbare Wege:

• externer Push-Mirror: https://github.com/michaelkaleschke-spec/homelab-infra
• lokaler Bare-Clone auf dem PC
• normaler lokaler Arbeits-Clone auf dem PC

Wenn weder GitHub-Mirror noch lokaler Repo-Clone verfuegbar sind, 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

Primaere lokale/off-site Restore-Quelle fuer die bestehende Flash-Konfiguration ist das Borg-Artefakt unraid-flash-config.tar.gz aus /mnt/user/backups/borg/dumps/latest. Dieses Archiv enthaelt /boot/config und muss wie Secret-Material behandelt werden.

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
• APP_KEY und ADMIN_PASSWORD fuer speedtest-tracker

Zusaetzlich rebuildbar (keine kritische Recovery-Quelle, koennen aus Provider-/App-UIs neu erzeugt werden):

• GLANCE_IMMICH_API_KEY, GLANCE_ADGUARD_USERNAME, GLANCE_ADGUARD_PASSWORD, GLANCE_SPEEDTEST_API_KEY fuer glance Community-/Live-Widgets

6.2.1 Restore-Quellen fuer Stack-ENV-Werte

Stack-ENV-Werte liegen nicht im Repo und nicht als Datei-Secret unter /mnt/user/appdata/secrets/. Sie sind nur an drei Stellen erreichbar; bei Recovery in dieser Reihenfolge pruefen:

1. Komodo-Mongo-Dump komodo-mongo.archive.gz unter /mnt/user/backups/borg/dumps/latest/. Solange Komodo selbst noch nicht laeuft, ist der Mongo-Dump die kanonische Quelle. Restore in eine Test-Mongo-Instanz, anschliessend Werte aus der stack-Collection lesen. Niemals Werte in andere Dokumente kopieren.
2. Vaultwarden Eintrag "Komodo Stack ENV / KalliLab CORE" (bzw. der entsprechende Eintrag pro Stack). Voraussetzung: Vaultwarden ist bereits restauriert (docs/RESTORE_MATRIX.md).
3. Externe Operator-Notiz (versiegelter Umschlag, Bankschliessfach, oder analoge Sicherung neben der Borg-Passphrase). Nur als Notfall-Quelle, wenn weder Komodo-Mongo noch Vaultwarden verfuegbar sind.

Reihenfolge-Konsequenz fuer den Bootstrap-Pfad in Phase 4 (Stufe 4 weiter unten):

• Vor dem Start von apps/paperless/, apps/immich/, apps/mail-archiver/ und ops/speedtest/ muessen die jeweiligen Stack-ENV-Werte in Komodo wieder hinterlegt sein.
• Wenn komodo-mongo.archive.gz frisch ist, koennen die Werte beim Komodo-Restart aus dem Dump zurueckgespielt werden, ohne dass jemand sie sieht.
• Wenn Vaultwarden vor Komodo restauriert wird (was hier nicht der Standardweg ist), kann auch von dort gelesen werden.

Paperless ist die wichtigste bewusste Ausnahme: PAPERLESS_DBPASS und PAPERLESS_REDIS sind seit der Hardening-Phase bewusst Stack-ENV (Paperless unterstuetzt _FILE fuer DB-Pass nicht). Ein Komodo-Mongo-Dump-Verlust ist daher fuer Paperless gleichbedeutend mit Re-Initialisierung der App-DB; in diesem Fall hilft nur ein Restore aus Vaultwarden oder externer Notiz.

Regel: Konkrete Werte werden nirgendwo im Repo, in Logs, in Doku-Kommentaren oder in ntfy-Meldungen wiedergegeben. Auch dieses Dokument haelt nur Variablennamen, Quellen und Reihenfolge fest, keine Werte.

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
• Details zu /mnt/user/services/ und Komodo/Gitea-Bootstrap stehen in docs/SERVICES_RECOVERY.md
• /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
• /mnt/user/backups/borg/dumps/latest/unraid-flash-config.tar.gz
• 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/ (PostgreSQL 18 runtime, historischer Stack-Name bleibt fuer Service-DNS stabil)
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 verfuegbar als App-Cache fuer Paperless (infra/redis ist historisch als "shared" angelegt, wird faktisch nur von Paperless genutzt)
• Git-Zugriff wiederhergestellt

Stufe 3 - Deploy-System

8. ops/komodo/ - Kaltstart-Anker, kein Auto-Deploy

Komodo wird in dieser Stufe bewusst nicht ueber Gitea-Webhook deployed. Der vollstaendige Bootstrap-Pfad ist in docs/SERVICES_RECOVERY.md Abschnitt "Komodo Bootstrap" als lineare Stufen A-F dokumentiert. Hier in der DR-Reihenfolge gilt der Einstiegspunkt:

• Recovery-Anker ist ops/komodo/docker-compose.yml aus dem Repo (lokaler Clone, GitHub-Mirror oder homelab-infra.bundle-Restore).
• Komodo-Stack-ENV-Werte (KOMODO_*) sind Stack-ENV-only und werden aus Vaultwarden oder externer Notiz wiederhergestellt (siehe docs/SECRETS_MAP.md Abschnitt "Stack-ENV-only Secrets - Restore-Wege").
• Erst nach erfolgreicher Validierung der Komodo-Web-UI und Periphery-Verbindung werden in den naechsten Stufen die produktiven Stacks aufgenommen.

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/ntfy/
16. apps/paperless-gpt/
17. apps/bentopdf/
18. ops/glance/
19. ops/borg-ui/
20. ops/filebrowser/
21. ops/glances/
22. ops/scrutiny/
23. ops/speedtest/
24. monitoring/
25. ops/hermes-agent/
26. 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
• Glance / Monitoring / 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.

Beim PostgreSQL-Restore beachten:

• vor einem produktiven Dump occ maintenance:mode --on setzen
• die produktive DB-Rolle kann von POSTGRES_USER abweichen; aktuell nutzt Nextcloud laut config.php die Rolle oc_admin
• nach Restore und erfolgreichem occ status den Wartungsmodus mit occ maintenance:mode --off beenden

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
• Unraid-Flash-Artefakt: unraid-flash-config.tar.gz plus .sha256 und Manifest im selben Zielpfad

Redis 8 Restore / Rollback

Redis-Instanzen laufen auf der 8.x-Schiene. Vor Major-Upgrades wird redis-cli SAVE ausgefuehrt und der jeweilige Datenpfad kopiert.

Aktive Pfade und Besonderheiten:

• Shared Redis: /mnt/user/appdata/redis, Passwort aus redis_password.txt, AOF aktiv.
• Nextcloud Redis: /mnt/user/appdata/nextcloud/redis, ohne Redis-Passwort, Snapshot-Persistenz.
• Immich Redis: cache/queue-only ohne bind-mounted Datenpfad; Restore-Wahrheit ist Immich Postgres + Foto-Dateien, nicht Redis.

Rollback:

1. Abhaengige App stoppen.
2. Redis stoppen.
3. Compose auf das vorherige Redis-7.4-Image zuruecksetzen.
4. Bei Shared/Nextcloud den vor dem Cutover kopierten Datenpfad zurueckkopieren.
5. Redis und App starten, redis-cli INFO server und App-Smoke pruefen.

PostgreSQL 18 Major-Upgrade / Rollback

Produktive PostgreSQL-18-Cluster verwenden das Docker-Image-Layout mit Host-Mount auf /var/lib/postgresql und PGDATA=/var/lib/postgresql/18/docker.

Aktive Datenpfade:

• Shared PostgreSQL: /mnt/user/appdata/postgresql18
• Mealie PostgreSQL: /mnt/user/appdata/mealie/postgres18
• Nextcloud PostgreSQL: /mnt/user/appdata/nextcloud/postgres18

Rollback-Altstaende, bis zur separaten Loeschfreigabe nicht entfernen:

• Shared PostgreSQL 17: /mnt/user/appdata/postgresql17
• Mealie PostgreSQL 17: /mnt/user/appdata/mealie/postgres
• Nextcloud PostgreSQL 17: /mnt/user/appdata/nextcloud/postgres

Restore-Reihenfolge fuer den Shared-Cluster:

1. Frischen PostgreSQL-18-Cluster starten.
2. Globals aus pg_dumpall --globals-only einspielen.
3. Den bekannten Bootstrap-Konflikt fuer CREATE ROLE mailarchiver; gezielt tolerieren bzw. herausfiltern, danach ALTER ROLE mailarchiver ... dennoch einspielen.
4. Datenbanken anlegen und Custom-Format-Dumps mit pg_restore einspielen.
5. Restore-Logs auf echte ERROR, FATAL und PANIC pruefen.

Immich ist bewusst nicht Teil dieses PostgreSQL-18-Laufs: Die produktive DB bleibt auf PostgreSQL 14 und nutzt das Immich-Postgres-Image mit VectorChord/pgvector. VectorChord-Backups brauchen zum Restore ein Image mit VectorChord; der alte pgvecto.rs-Datenpfad /mnt/user/appdata/immich_postgres bleibt bis zur separaten Loeschfreigabe als Rollback-Altstand erhalten.

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

Micha/homelab-infra wird als privater GitHub-Push-Mirror gespiegelt. Dieser Mirror ist der bevorzugte Repo-Bootstrap, falls Gitea selbst nach einem Ausfall noch nicht laeuft. Wenn weder GitHub-Mirror noch lokaler Clone verfuegbar sind, ist services/gitea/data selbst Teil des kritischen Wiederanlaufs.

---

11. Offene Vorbereitungs-To-dos

• Unraid-USB-/Flash-Backup regelmaessig ueber unraid-flash-config.tar.gz und optional Unraid Connect pruefen
• Borg-Passphrase ist laut Operator-Bestaetigung vom 2026-05-26 extern/offline hinterlegt; bei Reviews nur Existenz/Lesbarkeit der Offline-Kopie pruefen, nie den Wert dokumentieren
• 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.