Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
3bd35434d66b0859da4b5f3fc5f34fa22d290ec8
homelab-infra/docs/DISASTER_RECOVERY.md
T
Micha cfa02ce627 Document Komodo bootstrap in linear stages 
Add explicit stages A-F to docs/SERVICES_RECOVERY.md: host/docker
baseline, repo source, secrets order, Komodo start, web/GitOps
validation, tier stack rollout. Recovery anchor is ops/komodo/
docker-compose.yml; the self-stack is explicitly not the anchor.
Link DISASTER_RECOVERY Phase 4 stage 3 to the new bootstrap section
and the stack-env-only secrets section in SECRETS_MAP.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-27 20:01:20 +02:00

16 KiB
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
  • 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

  1. infra/postgresql17/
  2. security/authelia/
  3. infra/redis/
  4. 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

  1. 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

  1. security/vaultwarden/
  2. apps/paperless/
  3. apps/immich/
  4. apps/mealie/
  5. apps/mail-archiver/
  6. apps/nextcloud/

Stufe 5 - Restliche Apps und Ops

  1. apps/ntfy/
  2. apps/paperless-gpt/
  3. apps/bentopdf/
  4. ops/glance/
  5. ops/borg-ui/
  6. ops/filebrowser/
  7. ops/glances/
  8. ops/scrutiny/
  9. ops/speedtest/
  10. monitoring/
  11. ops/hermes-agent/
  12. 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.

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

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.

Reference in New Issue View Git Blame Copy Permalink