homelab-infra/docs/DECISIONS.md

Entscheidungs-Register (ADR-light)

Typ: Entscheidung · Stand: 2026-06-11 · Status: aktiv

Zentrales Register fuer Architektur- und Betriebsentscheidungen. Neueste oben. Jeder Eintrag: Entscheidung, Kontext, ggf. Alternativen und Review-Trigger. Lange Incident-Erzaehlungen gehoeren nicht hierher, sondern in den Commit bzw. Host-Report; hier steht das Destillat. Vorher lebten diese Eintraege verstreut in HOMELAB_ARCHITECTURE_MASTER_V2.md §13, docs/MASTER_TODO.md (Geparkt), docs/HARDWARE_INVENTORY.md und der Audit-Restliste.

---

2026-06-11 — Host-DNS-Fallback aktiv (AdGuard-SPOF entschaerft)

Entscheidung: Unraid-Host nutzt eth0 DNS server 1 = 192.168.178.58 (AdGuard) und DNS server 2 = 192.168.178.1 (FRITZ!Box) als Failover. Kontext: AdGuard war einziger LAN-Resolver; ein Recreate hat 2026-06 einen Bulk-Deploy zerlegt, weil Docker-Pulls am eigenen DNS-Container scheiterten. Der Fallback bleibt nur passiv aktiv (Go-Resolver springt erst bei Socket-Fehler weiter), der Filter wirkt im Normalbetrieb unveraendert. options rotate ist nicht gesetzt. Umsetzung der Empfehlung 3a aus dem Optimierungs-Assessment vom 2026-06-10. Runbook: docs/runbooks/komodo-bulk-deploy-dns.md. Review-Trigger: Wenn AdGuard durch eine andere Filter-Loesung ersetzt wird oder ein zweiter Host-Resolver verfuegbar ist.

2026-06-11 — Hetzner Storage Box: automatische Snapshots aktiv

Entscheidung: Automatische Snapshots auf der Hetzner Storage Box (BX11, u565255.your-storagebox.de) sind aktiv: taeglich um 05:30 UTC (nach dem Borg-Lauf 04:30 lokal), Retention 7 Tage, Snapshot-Verzeichnis sichtbar fuer Einzeldatei-Restore via .zfs/snapshot/. Kontext: Borg append-only ist bewusst nicht umgesetzt (siehe Eintrag 2026-06-01); damit war ein kompromittierter Host bisher in der Lage, auch das Off-site-Backup zu loeschen. Storage-Box-Snapshots sind host-seitig nicht loeschbar und im BX11-Tarif inklusive. Kosten: 0 EUR zusaetzlich. Umsetzung der Empfehlung 2 aus dem Optimierungs-Assessment vom 2026-06-10. Review-Trigger: Hetzner-Quota-Druck (aktuell 65 GB / 1 TB - viel Luft) oder Aenderung der Backup-Strategie.

2026-06-11 — Doku-Konsolidierung: ein Fakt, ein Zuhause

Entscheidung: Die Dokumentation wird nach docs/archive/2026/homelab-doku-optimierung-2026-06-11.md konsolidiert: MASTER_TODO.md ist die einzige Statusliste, dieses Register die einzige Entscheidungssammlung, docs/archive/ nimmt abgeschlossene Snapshots auf, Erledigtes verlaesst die Arbeitskopie. Keine Ordner-Restruktur des Bestands. Kontext: 74 Markdown-Dateien / ~9.400 Zeilen; einzelne Sachverhalte waren an 6–9 Stellen dokumentiert; vier parallele Statuslisten. Review-Trigger: Quartals-Gaertnern (siehe docs/REPO_MAP.md Doku-Regeln).

2026-06-06 — baerchen: BitLocker und Veeam Storage Encryption bewusst aus

Entscheidung: BitLocker bleibt auf allen Laufwerken deaktiviert; Veeam Storage Encryption bleibt aus (StorageEncryptionEnabled=False). Kontext: Recovery laeuft ueber das Veeam-Image auf dem lokalen SMB-Share; kein Key-Management-Aufwand, Restrisiko physischer Diebstahl akzeptiert. Review-Trigger: Off-host-Auslagerung des Windows-Images oder geaendertes Risikoprofil. Runbook: ops/windows-reinstall/docs/windows-image-backup-baseline.md.

2026-06-06 — Tailscale: natives Unraid-Plugin kanonisch, restriktive ACL

Entscheidung: Tailscale laeuft ausschliesslich als natives Unraid-Plugin (tailscale.plg, Subnet-Router, State im Flash-Backup); der redundante userspace-Docker-Stack host-services/tailscale/ wurde entfernt. Tailnet-ACL ist tag-basiert restriktiv (tag:server/tag:operator, tag:family schlafend), Default-Allow entfernt. Kontext: Zwei parallele tailscaled-Instanzen; nur die Plugin-Instanz routet. Details: docs/NETWORK_INVENTORY.md. Review-Trigger: Erstes reales Familiengeraet (Familien-Dienste in ACL konkretisieren).

2026-06-06 — Authelia: 2FA-Catch-all aktiv, OIDC-Rollout gestaffelt

Entscheidung: Catch-all *.kaleschke.info -> two_factor in Repo- und Host-Config. OIDC-SSO wird app-weise ausgerollt (live: Grafana, Mealie; deployed: Paperless). Immich- und Nextcloud-OIDC sowie Nextcloud-Operator-TOTP sind geparkt, bis Familien-Accounts existieren. Kontext: Nur der Operator hat aktuell einen Authelia-Account; Familien-SSO-Nutzen entsteht erst mit dem Onboarding. Runbook: docs/AUTHELIA_OIDC_PLAN.md. Review-Trigger: Family-Onboarding erreicht die App-Login-Ebene.

2026-06-05 — USV geparkt, Cold-Backup Hetzner-only, kein Strom-Monitoring

Entscheidung: Keine USV-Anschaffung dieses Quartal (Power-Loss bewusst akzeptiert). Off-site bleibt allein Hetzner-Borg, keine zweite rotierende Cold-Kopie. Stromverbrauch wird nicht gemessen (kein Messgeraet, kein Beschaffungs-Todo). Review-Trigger: USV: Q3-Review ab 2026-07-01, Hardware-Upgrade oder realer Stromausfall mit Datenfolge. Cold-Backup: Hetzner-Probleme oder stark wachsender Datenwert. Strom: nur bei Anschaffung eines Messgeraets.

2026-06-03 — Fix Common Problems Plugin entfernt, keine Neuinstallation

Entscheidung: FCP wurde deinstalliert und wird bewusst nicht wieder installiert. Kontext: Ein FCP-Scan hing 7 Tage in einem grep -R-Symlink-Loop ueber das gesamte Array (3 Cores 100 %, IOWAIT bis 55 %, Load 14.6 -> 1.08 nach Entfernung). Die abgedeckten Risiken uebernehmen Scrutiny, Monitoring-Stack, Posture-Check und Critical-Events-Watcher. Review-Trigger: keiner; Entscheidung ist final.

2026-06-01 — Borg append-only auf Hetzner nicht umgesetzt

Entscheidung: Kein append-only/forced-command auf der Storage Box. Kontext: Der forced-command-Test brach die Key-Auth und musste per Passwort-Recovery zurueckgesetzt werden; Nutzen/Betriebsrisiko-Verhaeltnis unguenstig. Kompensation (Storage-Box-Snapshots) siehe docs/homelab-optimierung.md Empfehlung 2. Review-Trigger: Hetzner bietet robusteren Mechanismus, oder Ransomware-Risikoprofil aendert sich.

2026-05-28 — Plex: Reclaim, Traefik-Route ohne ForwardAuth, kein Remote Access

Entscheidung: Plex-Server ist als Operator-Konto geclaimt; externer Zugriff laeuft ausschliesslich ueber Traefik/443 (plex.kaleschke.info, File-Provider-Ausnahme wegen Host-Netz), Plex Remote Access und WAN-Port 32400 bleiben aus, keine Authelia-ForwardAuth (native Plex-Auth). Kontext: Preferences waren nach dem Mai-Crash jungfraeulich; Claim-Token wurde nur als Shell-Inline-ENV genutzt, nie persistiert. Details: docs/SERVICE_CATALOG.md, HOMELAB_ARCHITECTURE_MASTER_V2.md §10.

2026-05-28 — Gitea-SSH (222) bleibt ohne WAN-Freigabe

Entscheidung: Port 222 wird nicht in der FRITZ!Box freigegeben. Kontext: Tailscale ist der Operator-Pfad, der GitHub-Mirror deckt DR-Bootstrap ab, SSH-Brute-Force-Vektor extern vermeiden.

2026-05-28 — paperless-gpt und BentoPDF bleiben aktiv

Entscheidung: Beide Container bleiben trotz geringer Nutzung. paperless-gpt-Abloese wird erst mit Paperless-NGX 3.0 (eigene KI-Features) neu bewertet; BentoPDF ist situatives Tool mit vernachlaessigbarem Footprint und ersetzt Stirling-PDF. Review-Trigger: Paperless-NGX-3.0-Release.

2026-05-26 — AdGuard-Admin nur auf Tailscale-IP, ohne Traefik/2FA

Entscheidung: Admin-UI bleibt auf 100.80.98.33:8082 (Tailscale-only) gebunden; bewusst keine Traefik-/2FA-Umstellung. DNS-Port 53 bleibt direkte Host-Port-Ausnahme. Review-Trigger: Aenderung des Tailnet-Zugangsmodells.

2026-05-25 — Ein Dienst pro Funktion: Jellyfin, Homepage, Uptime-Kuma entfernt

Entscheidung: Plex ist der einzige Medienserver, Glance das einzige Dashboard, Blackbox-Exporter + Prometheus-Alerts + Grafana ersetzen Uptime-Kuma. Kontext: Doppelte Dienste = doppelte Pflege/Attack-Surface. Removal-Checkliste: docs/WORKFLOW.md.

2026-05-17 — Monitoring-/Logging-Baseline

Entscheidung: monitoring/ ist der einzige Observability-Stack (Prometheus, Loki, Promtail, Grafana, Exporter, InfluxDB 3 Core). Loki intern ohne Route, Promtail mit read-only Docker-Socket, Loki-Daten sind Diagnosematerial mit Retention, keine Restore-Quelle. Alte Pfade ops/loki/ops/grafana-influxdb sind entfernt (Rollback nur via Git-Historie).

2026-05-05 — Stateful Digest-Pinning und Versionspolitik

Entscheidung: Tier-1-/stateful Dienste laufen mit sprechendem Versions-Tag plus Digest (z. B. postgres:17.x@sha256:...); mutable Tags wurden 2026-04-17 auf laufende Digests eingefroren. Digest-Pinning ist Reproduzierbarkeit, kein Upgrade-Mechanismus; echte Upgrades sind eigene Aenderungsbloecke. Renovate (live seit 2026-05-29) liefert PRs, kein Auto-Merge. Review-Trigger: Mutable-Tag-Restbestand siehe docs/homelab-optimierung.md Empfehlung 1.

2026-05-04 — Authelia ohne Redis-Session-Backend

Entscheidung: Authelia nutzt PostgreSQL fuer Storage, aber kein Redis-Session-Backend; nach Restart werden Sessions neu aufgebaut. Kontext: Haelt den Tier-1-Auth-Pfad einfach. infra/redis ist faktisch nur Paperless-Cache; Konsolidierung nach apps/paperless/ bleibt denkbar, unpriorisiert.

2026-05-04 — Komodo-Self-Stack: Reconcile-Regel nach Drift

Entscheidung: Der Komodo-Self-Stack laeuft aus /mnt/user/services/stacks/komodo/compose.yaml (Quelle: ops/komodo/docker-compose.yml). Bei Self-Stack-Drift kein pauschales docker compose up -d, wenn der Dry-run komodo-mongo recreaten wuerde; Core/Periphery gezielt mit --no-deps neu erstellen, Mongo unangetastet lassen. Kontext: Drift-Recovery 2026-05-04 (Repair-YAMLs aus /tmp); Sicherungen unter /mnt/user/appdata/komodo/_drift_backup_2026-05-04/.

2026-04-19 — Nextcloud als klassischer Stack, nicht AIO; native Auth

Entscheidung: Nextcloud laeuft als App + eigene PostgreSQL + eigene Redis (kein AIO), ohne zentrale ForwardAuth (Browser-/Client-/WebDAV-Flows brauchen native Auth).

2026-04-12 — Borg-Scope enthaelt bewusst /local/secrets

Entscheidung: Borg sichert ausgewaehltes Secret-Material (/local/secrets) als Teil der DR-Strategie; borg-ui hat dafuer breite, bewusste Mounts. Dumps statt Raw-DB-Pfade sind der primaere Restore-Weg. Kontext: ops/borg-ui/BACKUP_SCOPE.md.

2026-03-28/29 — GitOps-Fundament

Entscheidung: Komodo ersetzt Portainer als alleiniger Stack-Manager (Docker-Socket-Ausnahme, native Auth ohne pauschale ForwardAuth wegen Webhooks//ws/periphery). Traefik routet ausschliesslich ueber Docker-Labels; File-Provider nur fuer middlewares.yml, tls.yml, dashboards.yml (+ dokumentierte plex.yml-Ausnahme). AdGuard Home + Unbound ersetzen Pi-hole. Kontext: Konkurrierende @file-/@docker-Router hatten Fehlrouting verursacht; Regel: keine neuen Service-Routen im File-Provider.

Aelteres / Sonderfaelle

• Paperless Stack-ENV-Ausnahme: PAPERLESS_DBPASS/PAPERLESS_REDIS bleiben Komodo-Stack-ENV (kein _FILE-Support im Image); Konsequenzen fuer DR siehe docs/DISASTER_RECOVERY.md Phase 2.
• ddns-updater in frontend_net: braucht Cloudflare-API; backend_net ist internal.
• mail-archiver Hybrid: frontend_net (IMAP) + backend_net (DB), App-Auth zusaetzlich zu Authelia.
• Vollstaendige technische Ausnahmen-Liste mit Begruendung: HOMELAB_ARCHITECTURE_MASTER_V2.md §10 (bleibt dort autoritativ).