Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
Files
52fc007123272e46c1b0ac0a23fe650934545ff8
homelab-infra/ops/restore-tests/authelia-plan.md
T
Micha 52fc007123 fix(restore): authelia smoke without dump-restore, drop bogus env, disable ntp 
Erstlauf 2026-06-03 hat einen by-design-Konflikt offengelegt: pg_restore des
produktiven postgresql17-authelia.dump in eine Test-Instanz mit Wegwerf
AUTHELIA_STORAGE_ENCRYPTION_KEY scheitert im Authelia-Startup-Check mit
"the configured encryption key does not appear to be valid for this database".
Productive Storage-Werte werden mit dem produktiven Key verschluesselt; ein
Wegwerf-Key kann sie nicht entschluesseln. Smoke ist deshalb explizit auf
Config-Restore + Boot reduziert, nicht Daten-Decrypt.

Zwei Nebenbefunde aus demselben Lauf:
- AUTHELIA__SERVER__ADDRESS (Doppel-Underscore) wurde von Authelia 4.39
  abgelehnt ("configuration environment variable not expected"). ENV
  entfernt; server.address kommt eh aus der generierten configuration.yml.
- ntp-Startup-Check schlug fehl ("Could not determine the clock offset
  ... lookup time.cloudflare.com on 127.0.0.1:53: server misbehaving"),
  weil das isolierte Test-Compose-Netz keinen DNS-Resolver fuer NTP hat.
  Neuer Test-Config-Block setzt ntp.disable_startup_check: true.

Doku nachgezogen (Plan + Runbook): Encryption-Key-Konflikt ist explizit
als "nicht Teil dieses Smokes" dokumentiert; Fehler-Matrix hat Eintraege
fuer Doppel-Underscore-ENV und NTP-Lookup.

Frische des produktiven authelia-Dumps wird unveraendert ueber
check-restore-freshness.sh ueberwacht; Daten-Decrypt-Drill ist eine eigene
DR-Aufgabe mit kontrollierter Schluessel-Verwendung.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-03 08:27:40 +02:00

6.4 KiB
Raw Blame History

Authelia Restore Test Plan

Ziel

Nachweisen, dass die Authelia-Konfiguration aus dem produktiven Borg-Archiv in einer isolierten Testumgebung wieder lauffaehig ist und der HTTP-Health-Endpunkt antwortet, ohne dass dabei produktive Secrets, produktives Postgres oder produktiver SMTP-Versand beruehrt werden.

Bewusst nicht Teil dieses Tests:

  • Restore mit produktiven Authelia-Secrets. Der Test nutzt ausschliesslich Wegwerf-Werte fuer AUTHELIA_SESSION_SECRET, AUTHELIA_STORAGE_ENCRYPTION_KEY und AUTHELIA_STORAGE_POSTGRES_PASSWORD. SMTP- und Legacy-JWT-Env-Werte werden bewusst nicht gesetzt, damit Authelia keinen notifier.smtp-Block oder deprecated jwt_secret aus Env erzeugt.
  • SMTP-Realanruf an GMX. Die minimale Test-Konfiguration setzt nur den Filesystem-Notifier.
  • Forward-Auth gegen Traefik. Test laeuft nur auf 127.0.0.1:19091, keine Traefik-Route.
  • WebAuthn-/Duo-/OIDC-Identity-Provider-Endpunkte. Smoke prueft /api/health.
  • pg_restore des produktiven postgresql17-authelia.dump. Authelia verschluesselt Storage-Werte mit AUTHELIA_STORAGE_ENCRYPTION_KEY. Ein Restore mit produktiven Daten in eine Test-Instanz mit Wegwerf-Key schlaegt im Startup-Check by design fehl ("the configured encryption key does not appear to be valid for this database"). Frische des produktiven Dumps wird ueber check-restore-freshness.sh ueberwacht; Daten-Decrypt-Drill ist eine separate DR-Aufgabe und braucht eine eigene Sicherheits-Choreographie mit kontrollierter Schluessel-Verwendung. Beobachtet im Erstlauf 2026-06-03 (Commit-Reihe cacf77b..8d71dfb); seit dem 2026-06-03-Folgecommit ist der Dump-Restore explizit aus dem Smoke entfernt.

Quelle

  • Backup-Quelle: produktives Borg-Archiv (hetzner_borg_appdata_critical)
  • fachlich relevante Pfade im Archiv:
    • local/appdata/authelia/config (verpflichtend)
    • local/borg-dumps/latest/postgresql17-authelia.dump (existiert ggf. im Archiv; wird vom Smoke bewusst NICHT eingespielt, siehe oben)
  • produktive Secrets unter /mnt/user/appdata/secrets/authelia_*.txt werden nicht gemountet

Test-Ziel

  • Restore-Lab: /mnt/user/backups/restore-lab/authelia
  • Testdatenpfade:
    • /mnt/user/backups/restore-lab/authelia/config (restaurierte Originalkonfiguration + configuration.yml.original)
    • /mnt/user/backups/restore-lab/authelia/test-config (Runtime-Mount mit minimaler Test-configuration.yml)
    • /mnt/user/backups/restore-lab/authelia/postgres (Test-Postgres-Datadir)
    • /mnt/user/backups/restore-lab/authelia/dumps/latest/postgresql17-authelia.dump (falls extrahiert)
    • /mnt/user/backups/restore-lab/authelia/test-config/notifier/notifications.txt (Filesystem-Notifier-Ausgabe)
  • Testcontainer:
    • restoretest-authelia (Image-Pin wie Produktion)
    • restoretest-authelia-postgres (postgres:18.4, gleiche Major wie shared Postgres)
  • Testport: 127.0.0.1:19091:9091
  • Report-Ziel: /mnt/user/backups/restore-reports/authelia-YYYY-MM-DD.md

Schutzregeln

  • produktive Pfade /mnt/user/appdata/authelia/* werden nicht beschrieben
  • produktive Secret-Dateien /mnt/user/appdata/secrets/authelia_*.txt werden nicht gemountet
  • produktive shared PostgreSQL 18 wird nicht angesprochen (test-config/configuration.yml definiert nur Test-Postgres)
  • echter SMTP-Versand wird nicht ausgeloest (test-config/configuration.yml definiert nur Filesystem-Notifier)
  • produktive Domain auth.kaleschke.info wird nicht uebernommen
  • Testcontainer publishen nur auf 127.0.0.1, keine LAN-/Tailscale-Bindung
  • Borg-Passphrase wird aus /mnt/user/appdata/secrets/borg_repo_passphrase.txt gelesen und nirgendwo geloggt

Geplanter Ablauf

  1. Restore-Lab-Pfade leer anlegen
  2. local/appdata/authelia/config aus dem aktuellsten Borg-Archiv extrahieren
  3. minimale test-config/configuration.yml erzeugen; restaurierte Begleitdateien wie users_database.yml bleiben im Runtime-Mount, produktive externe Abhaengigkeiten werden nicht uebernommen; notifier auf Filesystem, ntp.disable_startup_check: true, storage auf Test-Postgres
  4. Test-Postgres mit ops/restore-tests/authelia-compose.test.yml frisch hochfahren (keine Daten aus Dump - siehe Encryption-Key-Begruendung oben)
  5. authelia config validate gegen test-config/configuration.yml laufen lassen
  6. restoretest-authelia starten und HTTP-Health http://127.0.0.1:19091/api/health pollen
  7. Report unter /mnt/user/backups/restore-reports/authelia-YYYY-MM-DD.md schreiben
  8. Testcontainer stoppen und Restore-Lab bereinigen (--keep-data ueberschreibt)

Smoke-Test

Minimal erfolgreich:

  • Borg-Extract der Authelia-Config gelingt
  • Test-Postgres startet healthy
  • authelia config validate laeuft ohne Fehler durch
  • HTTP 200 auf /api/health innerhalb 120 s

Optional spaeter:

  • vollstaendigen Auth-Flow gegen Test-User aus users_database.yml durchspielen
  • WebAuthn-Endpunkt /api/secondfactor/webauthn pruefen
  • ForwardAuth-Pfad gegen Mock-Backend testen

Bekannte Komplikationen

Risiko Beschreibung Mitigation
Testkonfig-Schema-Drift Authelia erwartet nach Upgrade andere Keys in der Minimal-Konfig bei config validate-Fehler Test-Block im Skript anpassen
SMTP-Startup-Check blockiert Start Wenn Authelia trotz disable_startup_check SMTP probiert Container-Logs lesen, ggf. Notifier-Block weiter haerten
NTP-Lookup im Test-Netz Container hat keinen DNS-Resolver fuer time.cloudflare.com im Smoke per ntp.disable_startup_check: true deaktiviert
Storage-Encryption-Key vs. Dump siehe "Bewusst nicht Teil dieses Tests" - der Smoke laeuft FRISCH ohne Dump by design - Daten-Decrypt-Drill ist separate Aufgabe
identity_validation Schema-Drift Aelteres/neueres Authelia-Schema erwartet andere Keys Validate-Config Output lesen, ggf. Test-Block anpassen
users_database.yml mit produktiven Hashes Daten werden ins Restore-Lab kopiert, aber niemals gemountet auf produktive Domain OK; Testpfad ist isoliert, kein Browser-Zugang ueber LAN

Noch offen vor dem ersten echten Lauf

  • Erstlauf --what-if als Plan-Check
  • Erstlauf --keep-data zur Beobachtung von SMTP-Startup-Verhalten
  • Validate-Config-Output zum Authelia-Schema-Stand pruefen
  • nach Erfolg: Schedule-Eintrag analog zu Vaultwarden (2. Samstag in geraden Monaten als Vorschlag, damit nicht mit Paperless kollidiert)

Status

  • Skript- und Compose-Scaffold abgelegt am 2026-06-02
  • noch kein echter Mini-Restore gelaufen - erster Lauf braucht Operator-Freigabe
Reference in New Issue View Git Blame Copy Permalink