18 KiB
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-13 - SolarEdge lokal ueber Modbus TCP angebunden
Entscheidung: SolarEdge wird in Home Assistant lokal ueber
solaredge_modbus_multi angebunden, nicht ueber die SolarEdge-Cloud-API. Der
Wechselrichter ist im LAN als 192.168.178.111 erreichbar, MAC-OUI
84:D6:C5 gehoert zu SolarEdge, Modbus TCP laeuft auf Port 1502, Device-ID
1. Die Integration liefert Inverter-, Smart-Meter- und Batterie-Entitaeten.
Kontext: Der Operator kann im SolarEdge-Portal keinen API-Key erzeugen; das
fruehere Setup lief bereits lokal. Der alte in der Doku genannte VONETS-Adapter
192.168.178.71 ist nicht erreichbar und bleibt kein verlaesslicher Zielpfad.
Die native HA-Core-Integration solaredge waere Cloud-Polling mit Site-ID/API-
Key; solaredge_local erwartet dagegen die lokale HTTP-SetApp-API unter
/web/v1/status, die am Wechselrichter nicht offen ist. Der vorhandene
HACS-/Custom-Component-Pfad solaredge_modbus_multi v3.2.5 passt zur realen
Schnittstelle und wurde ohne neue Downloads wiederverwendet.
Betriebsstand 2026-06-13: Config-Entry SolarEdge Local ist loaded,
Polling alle 60 Sekunden, Meter- und Batterie-Erkennung aktiv, Extras und
Power-Control-Schreibfunktionen deaktiviert. Relevante Energy-Dashboard-
Kandidaten:
sensor.solaredge_local_i1_ac_energy,
sensor.solaredge_local_i1_m1_ac_energy_imported,
sensor.solaredge_local_i1_m1_ac_energy_exported,
sensor.solaredge_local_i1_b1_energy_import,
sensor.solaredge_local_i1_b1_energy_export. Nach der Integration wurde ein
HA-native Backup erzeugt:
/mnt/user/appdata/homeassistant/backups/Custom_backup_2026.6.1_2026-06-13_14.59_48645373.tar.
Das HA Energy Dashboard wurde anschliessend mit Netz, PV und Speicher aus
SolarEdge Local konfiguriert und per energy/validate ohne Issues geprueft.
Kosten/Preise bleiben bis zur Tibber-Anbindung leer. Nach dieser UI-State-
Aenderung wurde ein weiteres HA-native Backup erzeugt:
/mnt/user/appdata/homeassistant/backups/Custom_backup_2026.6.1_2026-06-13_15.59_25670583.tar.
Trade-off: Die lokale Modbus-Integration passt zum Prinzip "lokal vor Cloud" und liefert deutlich bessere Betriebsdaten als die Cloud-API, ist aber eine HACS-/Custom-Integration und damit nicht durch HA-Core getestet. Bei Problemen zuerst Integration deaktivieren oder auf HA-Core-Cloud-Polling zurueckfallen, sobald Site-ID/API-Key verfuegbar sind.
Review-Trigger: HA-Core-Upgrade mit Custom-Integration-Warnungen,
Ausfaelle von 192.168.178.111:1502, Wechselrichtertausch/IP-Aenderung,
oder wenn Energie-Automationen schreibende Power-Control-Funktionen brauchen.
2026-06-13 - Ecowitt-Ingress: LAN-only Host-Bind 8123 umgesetzt
Entscheidung: Home Assistant bekommt einen LAN-only Host-Bind
192.168.178.58:8123:8123 (nur LAN-IP, nicht 0.0.0.0/WAN). Das Ecowitt-GW3000
pusht per HTTP direkt an den HA-Webhook. Damit ist die offene
Phase-2-Entscheidung (Eintrag 2026-06-12) zugunsten des LAN-Bind-Fallbacks
entschieden; ein Umbau des globalen Traefik HTTP-zu-HTTPS-Redirects entfaellt,
weil Ecowitt rein im LAN pusht und Traefik gar nicht braucht.
Kontext: Der globale web->websecure-Redirect auf EntryPoint-Ebene laesst
sich nicht sauber selektiv aushebeln. Der LAN-Bind ist analog zur dokumentierten
InfluxDB-8181-Ausnahme, WAN-sicher (FRITZ!Box forwardet nur 443 auf Traefik) und
ohne Traefik-Umbau. Der HA-Webhook ist nicht local_only; Schutz ist die
128-bit-Zufalls-Webhook-ID. Restrisiko: der Pfad ist theoretisch auch ueber
Traefik/443 erreichbar, praktisch aber unratbar.
Review-Trigger: Wenn der Webhook haerter abgesichert werden soll
(Traefik-IPAllowList auf /api/webhook/ oder local_only), oder bei Ausbau
auf Ecowitt-Langzeitspeicherung in InfluxDB.
2026-06-12 - Home Assistant als Container im GitOps-Stack
Entscheidung: Home Assistant laeuft neu als homeassistant Container im
Stack smart-home/, nicht als HAOS-VM und nicht als Supervised-Installation.
Mosquitto laeuft als eigener Container im selben Stack; Zigbee2MQTT und ESPHome
werden spaeter ebenfalls als eigenstaendige Container ergaenzt. HA haengt in
frontend_net fuer Traefik und in smarthome_net fuer MQTT/Zigbee2MQTT/ESPHome.
Das Fachrepo smart-home-kalli liefert versionierte HA-YAML-Dateien read-only;
.storage, secrets.yaml und Integrations-State bleiben in
/mnt/user/appdata/homeassistant.
Kontext: Das fruehere HAOS-VM-Setup ging bei einem Crash ohne brauchbares Backup verloren. Das Homelab betreibt produktive Dienste inzwischen ueber Gitea, Komodo, Compose, Renovate und Borg. HA Container passt in dieses Betriebsmodell und vermeidet eine zweite Update-/Backup-Welt. Supervised ist kein Zielpfad mehr; HAOS bleibt die Alternative, falls Add-on-Komfort, Matter/Thread/HomeKit-Discovery oder Host-nahe HA-Funktionen wichtiger werden als GitOps-Konformitaet.
Betriebsstand 2026-06-13: Owner-Onboarding ist abgeschlossen, die
temporaere Authelia-Onboarding-Guard-Middleware ist entfernt, smart-home
existiert als Komodo-Stack mit Gitea-Webhook, HA-native backup.create erzeugt
ein lesbares Backup-Artefakt, und der Mosquitto-Broker besteht einen
authentifizierten Publish/Subscribe-Smoke. Die Restore-Probe wurde am
2026-06-13 erfolgreich abgeschlossen: HA-native Backup + Mosquitto-Appdata +
Fachrepo-Clone wurden isoliert gestartet, HA HTTP/API/check_config waren gruen,
MQTT Publish/Subscribe und retained Topic nach Broker-Restart waren gruen.
Report: /mnt/user/backups/restore-reports/homeassistant-2026-06-13.md.
Die HA-MQTT-Integration wurde anschliessend am 2026-06-13 ueber den
Home-Assistant-Config-Flow verbunden; Config-Entry smarthome-mosquitto ist
loaded, Mosquitto sieht den HA-Client mit User homeassistant, und
check_config ist gruen. Damit ist die Foundation abgeschlossen. Naechster
Produktivschritt ist Tibber, danach SolarEdge mit bewusster Entscheidung
zwischen schneller Cloud-Integration und lokalem Modbus-TCP.
Review-Trigger: Viele mDNS-/SSDP-abhaengige lokale Integrationen (HomeKit, Cast, Matter/Thread), Bedarf an HA-Add-ons als Betriebsstandard, oder wiederholte Probleme durch Bridge-Netzwerkbetrieb.
2026-06-12 - Ecowitt-Ingress bleibt bewusste Phase-2-Entscheidung
Entscheidung: In Phase 1 wird kein Host-Port 8123 fuer Home Assistant
veroeffentlicht. Ecowitt wird spaeter entweder ueber eine gezielte
Traefik-HTTP-Ausnahme fuer den Webhook-Pfad angebunden oder, falls der globale
HTTP-zu-HTTPS-EntryPoint-Redirect nicht sauber selektiv abloesbar ist, ueber
einen dokumentierten LAN-only Host-Port 8123.
Kontext: Ecowitt kann nur HTTP und kein HTTPS. Traefik hat aktuell einen
globalen web -> websecure Redirect auf EntryPoint-Ebene. Ein normaler
HTTP-Router kann diese Regel voraussichtlich nicht umgehen, ohne Traefik selbst
umzubauen. Deshalb wird die Entscheidung nicht vorgezogen.
Review-Trigger: Start der Ecowitt-/InfluxDB-Phase oder Umbau der Traefik HTTP-Redirect-Architektur.
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_REDISbleiben Komodo-Stack-ENV (kein_FILE-Support im Image); Konsequenzen fuer DR siehedocs/DISASTER_RECOVERY.mdPhase 2. - ddns-updater in
frontend_net: braucht Cloudflare-API;backend_netist 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).