Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
b7dfdad6215e3aa4212e1704d487304fcf7eeb34
homelab-infra/docs/DISASTER_RECOVERY.md
T

11 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
  • 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/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

  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 als shared Cache fuer abhaengige Apps verfuegbar
  • Git-Zugriff wiederhergestellt

Stufe 3 - Deploy-System

  1. ops/komodo/

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