Micha
0fabed4d1a
LAN-only Host-Bind 192.168.178.58:8123 fuer den Ecowitt-HTTP-Push dokumentiert: DECISIONS-Eintrag (loest Phase-2-Frage), Architektur-Master Ausnahme 10, SERVICE_CATALOG. Webhook + LAN-Endpunkt verifiziert; offen bleibt nur die GW3000-Customized-Server-Konfiguration am Geraet. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
206 lines
15 KiB
Markdown
206 lines
15 KiB
Markdown
# 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 - 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_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).
|