homelab-infra/docs/RESTORE_MATRIX.md

Restore Matrix - KalliLab CORE

Diese Matrix beschreibt fuer die wichtigsten Dienste:

• was die fuehrende Restore-Quelle ist
• welche Pfade oder Dumps relevant sind
• welche Secrets gebraucht werden
• wovon der Dienst abhaengt
• wie ein sinnvoller Smoke-Test aussieht

Sie ist die fachliche Ergaenzung zu docs/DISASTER_RECOVERY.md.

---

Legende

• Fuehrende Quelle = die primaere Restore-Wahrheit fuer diesen Dienst
• Datei-Restore = relevante Verzeichnisse / Volume-Pfade
• Dump / DB = relevante Dump-Artefakte oder Datenbankabhaengigkeiten
• Secrets / ENV = Dinge, die vor dem Start wieder da sein muessen
• Smoke-Test = minimaler Nachweis, dass der Restore wirklich greift

---

Tier 1 - Kritisch fuer Wiederanlauf

Dienst	Fuehrende Quelle	Datei-Restore	Dump / DB	Secrets / ENV	Abhaengigkeiten	Smoke-Test
Traefik	Share / Borg	/mnt/user/appdata/traefik, besonders dynamic/, letsencrypt, secrets	keine eigene DB	cloudflare_dns_api_token	frontend_net, backend_net	https://traefik.kaleschke.info erreichbar, Dashboard ueber Authelia
AdGuard Home	Share / Borg	/mnt/user/appdata/adguard/conf	keine	keine zusaetzlichen Repo-Secrets dokumentiert	dns_net, frontend_net	DNS-Aufloesung funktioniert
Tailscale	Share / Borg	/mnt/user/appdata/tailscale	keine	Tailscale-State im Pfad	Host-Netz	Tailscale verbunden
PostgreSQL 17	Share + Dumps	/mnt/user/appdata/postgresql17	postgresql17-globals.sql, postgresql17-mailarchiver.dump, postgresql17-paperless.dump, optional postgresql17-authelia.dump	postgres_password.txt	backend_net	DB startet, Ziel-Datenbanken vorhanden
Redis	Share / Host	/mnt/user/appdata/redis	keine	redis_password.txt	backend_net	Redis startet, Apps verbinden sich
Authelia	Borg	/mnt/user/appdata/authelia/config, /mnt/user/appdata/secrets/*authelia*	Shared PostgreSQL, optional Dump postgresql17-authelia.dump	JWT/Session/Storage/Postgres-Secret-Dateien	PostgreSQL 17, Redis, Traefik	Login-Seite und ForwardAuth funktionieren
Gitea	Borg / Share	/mnt/user/services/gitea/data	SQLite in /data	keine separaten Secret-Dateien dokumentiert	Traefik	Web-UI erreichbar, Repo sichtbar, SSH-Port reagiert
Komodo	Borg / Share	/mnt/user/appdata/komodo/core, /mnt/user/appdata/komodo/periphery	komodo-mongo.archive.gz falls verifiziert	komodo_mongo_password.txt, KOMODO_* Stack ENV	Traefik, Mongo, Gitea	UI erreichbar, Periphery verbunden
Vaultwarden	Borg / Share	/mnt/user/appdata/vaultwarden	dateibasiert	vaultwarden_admin_token.txt	Traefik	Login-Seite erreichbar, Tresor-Daten sichtbar

---

Tier 2 - Wichtige Anwendungen

Dienst	Fuehrende Quelle	Datei-Restore	Dump / DB	Secrets / ENV	Abhaengigkeiten	Smoke-Test
Paperless-ngx	Borg + Dumps	/mnt/user/appdata/paperless-ngx/data, /mnt/user/documents/paperless, /mnt/user/documents/paperless/export, /mnt/user/documents/scans_inbox	postgresql17-paperless.dump	PAPERLESS_DBPASS, PAPERLESS_REDIS	PostgreSQL 17, Redis, Traefik	Web-UI startet, Dokumente vorhanden
Mealie	Borg + Dump	/mnt/user/appdata/mealie/data, optional /mnt/user/appdata/mealie/postgres bei lokalem Share-Weiterbetrieb	mealie.dump	mealie_postgres_password.txt	mealie-postgres, Traefik	UI startet, Rezepte vorhanden
Immich	Borg + Dump	/mnt/user/photos/immich, /mnt/user/photos/family_archive	immich.dump	IMMICH_DB_PASSWORD, immich_postgres_password.txt	immich_postgres, immich_redis, Traefik	UI startet, Medienbibliothek sichtbar
Mail-Archiver	Borg + Shared Dump	/mnt/user/appdata/mailarchiver/data-protection-keys	postgresql17-mailarchiver.dump	MAILARCHIVER_DB_CONNECTION, MAILARCHIVER_AUTH_PASSWORD	PostgreSQL 17, Traefik	Web-UI startet, Archiv laesst sich oeffnen
Nextcloud	Borg + Share	/mnt/user/appdata/nextcloud/html, /mnt/user/appdata/nextcloud/postgres, /mnt/user/appdata/nextcloud/redis, /mnt/user/documents/nextcloud-data	app-eigene PostgreSQL unter /mnt/user/appdata/nextcloud/postgres	nextcloud_admin_user.txt, nextcloud_admin_password.txt, nextcloud_postgres_password.txt	nextcloud-postgres, nextcloud-redis, Traefik	Web-UI startet, Login funktioniert, Dateien sichtbar
Homepage	Borg / Share	/mnt/user/appdata/homepage	keine	HOMEPAGE_VAR_*	Traefik, Authelia	Dashboard startet, Widgets laden
ntfy	Borg / Share	/mnt/user/appdata/ntfy	keine	keine besonderen Secret-Dateien dokumentiert	Traefik	UI und Push-Endpunkt erreichbar
Paperless-GPT	Borg / Share	/mnt/user/appdata/paperless-gpt	keine eigene DB	PAPERLESS_API_TOKEN	Traefik, Paperless	UI startet, Konfiguration vorhanden

---

Tier 3 - Rebuildbar / Sekundaer

Dienst	Fuehrende Quelle	Datei-Restore	Dump / DB	Secrets / ENV	Abhaengigkeiten	Smoke-Test
Borg UI	Borg / Share	/mnt/user/appdata/borg-ui/data	keine eigene DB	Borg-Repo-Creds in /data	Traefik	UI startet, Repo-Verbindung bekannt
Backrest	Share	/mnt/user/appdata/backrest/*	keine	SSH-/Repo-Creds im Mount	Traefik	UI startet
Uptime Kuma	Share	/mnt/user/appdata/uptime-kuma	keine	keine besonderen Secret-Dateien dokumentiert	Traefik, Authelia	Monitore vorhanden
Filebrowser	Share	/mnt/user/appdata/filebrowser	keine	keine separaten Secret-Dateien dokumentiert	Traefik, Authelia	UI startet
Glances	Rebuildbar	kein kritischer Zustand	keine	keine	Traefik, Authelia	UI startet
Scrutiny	Teilweise rebuildbar	/mnt/user/appdata/scrutiny falls gewuenscht	InfluxDB bewusst nicht Teil des Critical-Scope	keine	Traefik, Authelia	UI startet, Laufwerke sichtbar
Speedtest Tracker	Share	/mnt/user/appdata/speedtest-tracker/config	SQLite im App-Pfad	APP_KEY, ADMIN_PASSWORD	Traefik, Authelia	UI startet
BentoPDF	Rebuildbar	keine kritische Persistenz; alte Stirling-PDF-Daten unter /mnt/user/appdata/stirling-pdf bis zur Abnahme behalten	keine	keine separaten Secret-Dateien dokumentiert	Traefik, Authelia	UI startet, PDF-Tools verfuegbar, Office-Konvertierung ueber HTTPS funktioniert
Grafana	Share	/mnt/user/appdata/grafana, inklusive provisioning/datasources/influxdb.yml	SQLite im App-Pfad	grafana_admin_password.txt, grafana_influxdb_token.txt	Traefik, Authelia, InfluxDB 3 Core	UI startet, InfluxDB-Datenquelle testet erfolgreich
InfluxDB 3 Core	Share	/mnt/user/appdata/influxdb3/data, /mnt/user/appdata/influxdb3/plugins	dateibasierter Object Store	influxdb3_admin_token.json	internes grafana_influx_internal Netz	homelab-Datenbank vorhanden, Grafana kann SQL-Abfrage ausfuehren
ddns-updater	Rebuildbar	geringe Persistenzrelevanz	keine	Provider-Zugang ueber Stack ENV	Internetzugang	Update-Job laeuft

---

Dumps und Restore-Artefakte

Aktuell relevante Dump-Artefakte unter /mnt/user/backups/borg/dumps/latest:

• postgresql17-globals.sql
• postgresql17-mailarchiver.dump
• postgresql17-paperless.dump
• postgresql17-authelia.dump (optional / wenn vorhanden)
• mealie.dump
• immich.dump
• komodo-mongo.archive.gz (noch gesondert verifizieren)

Die Dump-Erzeugung ist host-seitig ueber ops/borg-ui/scripts/pre-backup-dumps.sh vorgesehen.

---

Praktische Restore-Regeln

• Nicht mehrere kritische Dienste gleichzeitig restaurieren.
• Erst die Abhaengigkeiten wiederherstellen, dann die App.
• Bei Unsicherheit zuerst in Testpfade oder Testinstanzen pruefen.
• Der minimale Erfolg ist nicht "Container startet", sondern "fachlicher Smoke-Test gelingt".

---

Erste sinnvolle Referenz-Restores

Wenn weitere Restore-Uebungen dokumentiert werden sollen, sind diese Dienste besonders geeignet:

1. gitea
2. paperless-ngx
3. vaultwarden

Sie liefern hohen Erkenntnisgewinn ohne den kompletten Homelab-Neuaufbau zu brauchen.