homelab-infra/ops/restore-tests/authelia-runbook.md

Authelia Restore Runbook

Status

Skript und Test-Compose sind validiert. Erstlauf 2026-06-03 erfolgreich: Config aus Borg extrahiert, minimale Test-Konfiguration validiert, frisches Test-Postgres gestartet, HTTP /api/health 200. Report: /mnt/user/backups/restore-reports/authelia-2026-06-03.md. Authelia ist Tier-1-kritisch, deshalb bleibt dieser Test bewusst konservativ: Smoke-Test prueft nur Config-Validate + HTTP-Health, kein vollstaendiger Auth-Flow und kein produktiver Dump-Restore.

Vorbedingungen

• Borg-Quelle ist verfuegbar
• borg-ui-Container laeuft
• Borg-Passphrase-Datei vorhanden: /mnt/user/appdata/secrets/borg_repo_passphrase.txt
• borg-ui mountet die Passphrase im Container als /local/secrets/borg_repo_passphrase.txt
• aktuelles Borg-Archiv enthaelt local/appdata/authelia/config
• optional: local/borg-dumps/latest/postgresql17-authelia.dump
• Testpfade unter /mnt/user/backups/restore-lab/ und /mnt/user/backups/restore-reports/ sind freigegeben
• Port 127.0.0.1:19091 frei
• freier Speicher unter /mnt/user/backups/restore-lab/authelia (~200 MB reichen)

Bestaetigter Host-Stand (Soll)

• produktiver Authelia-Container: authelia mit Image authelia/authelia:4.39.20@sha256:1b363e9279e742397966333f364e0876ae02bf5c876de73e83af6d48c57ff51b
• produktiver Config-Pfad: /mnt/user/appdata/authelia/config
• produktive Secrets: /mnt/user/appdata/secrets/authelia_*.txt (werden vom Test nicht gebraucht)
• produktive Storage: shared PostgreSQL 18 (wird vom Test nicht angesprochen)

Erster Lauf - trockene Variante

bash /mnt/user/services/homelab-infra/ops/restore-tests/authelia-restore-test.sh --what-if

Erwartete Ausgabe: nur Plan-Output, kein Docker-Start, kein Borg-Extract.

Erster Lauf - echter Test (Operator-freigegeben)

bash /mnt/user/services/homelab-infra/ops/restore-tests/authelia-restore-test.sh --keep-data

Bei Erfolg:

• Report unter /mnt/user/backups/restore-reports/authelia-YYYY-MM-DD.md
• Restore-Lab-Daten bleiben mit --keep-data erhalten
• ohne --keep-data wird das Restore-Lab geloescht; bei Fehler wird es nach /mnt/user/backups/restore-lab/_failed/authelia-... verschoben

Smoke-Test-Pruefungen

Minimal erwartet im Report:

• Borg extract of config: ok
• Test-Postgres healthy
• authelia config validate: ok
• HTTP /api/health status: 200

Fehlerfaelle

Symptom	Ursache	Massnahme
config validate failt mit notifier Block	Testkonfig enthaelt mehr als einen Notifier	test-config/configuration.yml pruefen; Minimal-Test-Block im Skript anpassen
config validate failt mit session.domain	aelteres/neueres Schema	Test-session:-Block an reales Authelia-Schema anpassen
config validate failt mit access_control default_policy	Authelia >=4.39 verlangt ohne Rules two_factor/one_factor	Test-Block ist bereits auf two_factor gesetzt; bei weiterer Schema-Aenderung anpassen
HTTP-Timeout 120 s	Authelia haengt in Postgres-Schema-Migration	docker logs --tail 200 restoretest-authelia lesen, ggf. Wartezeit erhoehen
encryption key does not appear to be valid for this database	jemand hat pg_restore des produktiven Dumps wieder eingebaut	pg_restore ist seit 2026-06-03 bewusst NICHT mehr Teil dieses Smokes - siehe Plan/Skript-Doku; nicht re-aktivieren ohne kontrollierte Encryption-Key-Choreographie
SMTP-Connect im Log	Testkonfig oder Env erzeugt unerwartet SMTP	test-config/configuration.yml und AUTHELIA_*SMTP* Env pruefen
Could not determine the clock offset	DNS-Lookup time.cloudflare.com failt im isolierten Test-Netz	ntp.disable_startup_check: true ist im Test-Config-Block bereits gesetzt; bei Aenderung beibehalten
configuration environment variable not expected: AUTHELIA__SERVER__ADDRESS	Doppel-Underscore ENV im Compose	seit 2026-06-03 entfernt; server.address kommt aus configuration.yml

Cleanup

• bei Erfolg ohne --keep-data: rm -rf /mnt/user/backups/restore-lab/authelia und Extract-Cache
• bei Fehler: Datenpfad wird via preserve_on_failure nach /mnt/user/backups/restore-lab/_failed/authelia-... umbenannt

Produktive Authelia-Container, produktive Secrets, produktive Postgres-DB und produktiver SMTP-Account werden niemals beruehrt.

Schedule

Empfohlener Schedule nach erfolgreichem Erstlauf: zweimonatlich (2. Samstag in geraden Monaten), damit nicht mit Paperless kollidierend.

Festgelegte Entscheidungen

• Test-Compose nutzt denselben Image-Digest wie Produktion.
• Wegwerf-Secrets ausschliesslich im Test-Compose; niemals produktive Authelia-Secrets einsetzen.
• Test-Postgres ist isoliert; produktive shared PostgreSQL 18 wird nicht angesprochen.
• Notifier wird auf Filesystem umgebogen; KEIN echter SMTP-Versand.
• Test-Port nur auf 127.0.0.1:19091, keine LAN-/Traefik-Anbindung.
• Borg-Passphrase wird aus Host-Secret-Datei gelesen und nirgendwo geloggt.