feat: add smart home runtime foundation

2026-06-12 20:38:03 +02:00
parent 630ee8dd90
commit ce6f5c72dd
10 changed files with 285 additions and 4 deletions
@@ -0,0 +1,58 @@
+# Smart Home Runtime Stack
+
+Runtime-Zustand fuer Home Assistant auf Kallilabcore. Dieser Ordner gehoert zu
+`homelab-infra`, weil Komodo den Stack deployt und Renovate die Images pflegt.
+
+## Dienste
+
+- `homeassistant`: Home Assistant Container, erreichbar ueber Traefik unter
+  `https://home.kaleschke.info`
+- `smarthome-mosquitto`: interner MQTT-Broker fuer Home Assistant, spaeter
+  Zigbee2MQTT und ESPHome
+
+## Abhaengigkeiten
+
+- `frontend_net` existiert bereits und wird von Traefik genutzt.
+- `smarthome_net` wird durch diesen Stack angelegt und ist `internal: true`.
+- Das Fachrepo `smart-home-kalli` muss auf dem Unraid-Host unter
+  `/mnt/user/services/smart-home-kalli` liegen. Nur ausgewählte YAML-Dateien
+  werden read-only nach `/config` gemountet; `.storage` bleibt in
+  `/mnt/user/appdata/homeassistant`.
+- Vor dem ersten Start muessen diese Dateien hostseitig angelegt werden:
+  - `/mnt/user/appdata/homeassistant/secrets.yaml`
+  - `/mnt/user/appdata/homeassistant/trusted_proxies.yaml`
+  - `/mnt/user/appdata/mosquitto/config/passwordfile`
+  - `/mnt/user/appdata/mosquitto/config/aclfile`
+
+Das detaillierte Host-Bootstrap-Runbook liegt unter
+`docs/runbooks/smart-home-bootstrap.md`.
+
+## MQTT Bootstrap
+
+Beispiel fuer den initialen Home-Assistant-MQTT-User auf dem Unraid-Host:
+
+```sh
+mkdir -p /mnt/user/appdata/mosquitto/config
+docker run --rm -it \
+  -v /mnt/user/appdata/mosquitto/config:/mosquitto/external_config \
+  eclipse-mosquitto:2.0.22 \
+  mosquitto_passwd -c /mosquitto/external_config/passwordfile homeassistant
+cat > /mnt/user/appdata/mosquitto/config/aclfile <<'EOF'
+user homeassistant
+topic readwrite #
+EOF
+```
+
+LAN-Port `1883` bleibt in Phase 1 geschlossen. Eine Portfreigabe fuer externe
+MQTT-Clients wird erst in der ESPHome-Phase mit ACLs und per-Device-Usern
+ergaenzt.
+
+## Ecowitt
+
+Ecowitt wird nicht in Phase 1 exponiert. Wegen des globalen Traefik
+HTTP-zu-HTTPS-Redirects bleibt die Ingress-Entscheidung offen:
+
+1. Traefik-HTTP-Ausnahme nur fuer den Ecowitt-Webhook, falls der globale
+   EntryPoint-Redirect gezielt abloesbar ist.
+2. Dokumentierter LAN-only Host-Port `8123` als Fallback, wenn Option 1 den
+   bestehenden Traefik-Standard zu stark verbiegt.