homelab-infra/docs/runbooks/smart-home-bootstrap.md

Smart-Home Bootstrap

Ziel: Den Stack smart-home/ auf Kallilabcore initial startklar machen, ohne Secrets oder UI-State ins Git zu schreiben.

1. Fachrepo auf dem Host bereitstellen

cd /mnt/user/services
git clone https://git.kaleschke.info/Micha/smart-home-kalli.git smart-home-kalli
cd smart-home-kalli
git checkout main

Der Home-Assistant-Container mountet daraus einzelne YAML-Dateien read-only nach /config.

2. Home-Assistant-Appdata vorbereiten

mkdir -p /mnt/user/appdata/homeassistant
cp /mnt/user/services/smart-home-kalli/secrets-template/secrets.yaml.example \
  /mnt/user/appdata/homeassistant/secrets.yaml
cp /mnt/user/services/smart-home-kalli/secrets-template/trusted_proxies.yaml.example \
  /mnt/user/appdata/homeassistant/trusted_proxies.yaml

Danach trusted_proxies.yaml auf das echte Traefik-/frontend_net-Subnetz anpassen:

docker network inspect frontend_net

3. Mosquitto vorbereiten

mkdir -p /mnt/user/appdata/mosquitto/config \
  /mnt/user/appdata/mosquitto/data \
  /mnt/user/appdata/mosquitto/log

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

Das initiale Passwort anschliessend in /mnt/user/appdata/homeassistant/secrets.yaml eintragen. LAN-Port 1883 bleibt in Phase 1 geschlossen.

4. Stack deployen

Komodo-Stack:

• Repo: homelab-infra
• Pfad: smart-home/docker-compose.yml
• Branch: nach Review master
• Status 2026-06-13: Stack smart-home existiert in Komodo, Gitea-Webhook ist aktiv, deployed_hash == latest_hash.

Nach dem Start pruefen:

docker ps --filter name=homeassistant
docker ps --filter name=smarthome-mosquitto
docker logs --tail=100 homeassistant
docker logs --tail=100 smarthome-mosquitto

5. Smoke-Test

• https://home.kaleschke.info zeigt die Home-Assistant-Oberflaeche.
• Nach Owner-Onboarding: keine Authelia-ForwardAuth mehr vor HA; HA nutzt native Auth plus http.ip_ban_enabled.
• trusted_proxies.yaml deckt das frontend_net ab; damit wertet HA die echte Client-IP aus X-Forwarded-For aus.
• Keine Trusted-Proxy-Fehler im HA-Log.
• MQTT-Broker-Smoke: homeassistant-User aus secrets.yaml kann gegen smarthome-mosquitto:1883 publish/subscriben.
• HA-MQTT-Integration ist verbunden: Config-Entry smarthome-mosquitto ist loaded, Mosquitto sieht einen HA-Client mit User homeassistant.
• HA-native Backup-Erstellung funktioniert; Beispielartefakt: /mnt/user/appdata/homeassistant/backups/Custom_backup_2026.6.1_2026-06-13_08.25_38034438.tar.
• Backup-Artefakt ist lesbar (backup.json, homeassistant.tar.gz).
• Agent-API-Tokens liegen als Host-Secrets unter /mnt/user/appdata/secrets/ha_token_codex und /mnt/user/appdata/secrets/ha_token_claude; Werte nie ausgeben oder in Git schreiben. Die Tokens sind nur mit erhaltenem HA-Auth-State in .storage brauchbar und bei Verdacht in HA zu widerrufen.

6. Fachrepo-Update

Das Fachrepo /mnt/user/services/smart-home-kalli ist kein eigener Komodo-Stack. Aenderungen wirken erst nach diesem Host-Ablauf:

cd /mnt/user/services/smart-home-kalli
git pull --ff-only origin main
docker compose -f /mnt/user/services/stacks/smart-home/smart-home/docker-compose.yml \
  up -d --force-recreate homeassistant

Der Force-Recreate ist Pflicht, weil configuration.yaml, automations.yaml, scripts.yaml und scenes.yaml als Einzeldateien in den Container gemountet werden. Nach einem git pull kann Docker sonst noch den alten Datei-Inode sehen (Stale file handle).

7. UI-Editor-Politik

automations.yaml, scripts.yaml und scenes.yaml sind read-only aus Git gemountet. Der Home-Assistant-UI-Editor fuer diese Dateien ist deshalb nicht der primaere Schreibweg. Automationen und Scripts werden in Git gepflegt; UI-State und Integrations-State bleiben in .storage und werden per Borg gesichert.

8. Abnahmebedingung

Vor produktiven Energie-Automationen muss ein Restore-Test fuer /mnt/user/appdata/homeassistant, /mnt/user/appdata/mosquitto und den Clone /mnt/user/services/smart-home-kalli dokumentiert sein.

Wichtig: Ein erfolgreich erzeugtes HA-Backup ist nur die Voraussetzung. Das Gate ist erst geschlossen, wenn eine Restore-Probe in einem isolierten Testpfad dokumentiert ist.

Status 2026-06-13: Gate geschlossen. Die isolierte Restore-Probe war erfolgreich:

• Report: /mnt/user/backups/restore-reports/homeassistant-2026-06-13.md
• Test: HA-native Backup + Mosquitto-Appdata + Fachrepo-Clone
• Ergebnis: HA HTTP/API/check_config gruen, MQTT Publish/Subscribe und retained Topic nach Broker-Restart gruen

Status 2026-06-13: HA-MQTT-Integration ist produktiv verbunden.

Verifikation:

TOKEN=$(cat /mnt/user/appdata/secrets/ha_token_codex)
curl -ksS -H "Authorization: Bearer $TOKEN" \
  https://home.kaleschke.info/api/config/config_entries/entry
docker logs --tail=120 smarthome-mosquitto
docker exec homeassistant python -m homeassistant --script check_config --config /config

Erwartung: Ein MQTT-Config-Entry smarthome-mosquitto mit Status loaded, ein Mosquitto-Client mit User homeassistant, und check_config ohne Fehler.

9. SolarEdge lokal

Status 2026-06-13: SolarEdge ist lokal per Modbus TCP angebunden.

• Integration: HACS/Custom solaredge_modbus_multi v3.2.5
• HA-Config-Entry: SolarEdge Local, Status loaded
• Wechselrichter: 192.168.178.111:1502
• Modbus Device-ID: 1
• Optionen: Polling 60 Sekunden, Meter-Erkennung aktiv, Batterie-Erkennung aktiv, Extras aus, Power-Control aus

Verifikation:

TOKEN=$(cat /mnt/user/appdata/secrets/ha_token_codex)
curl -ksS -H "Authorization: Bearer $TOKEN" \
  https://home.kaleschke.info/api/config/config_entries/entry
curl -ksS -H "Authorization: Bearer $TOKEN" \
  https://home.kaleschke.info/api/states
docker exec homeassistant python -m homeassistant --script check_config --config /config

Wichtige Energy-Dashboard-Kandidaten:

• PV-Produktion: sensor.solaredge_local_i1_ac_energy
• Netzbezug: sensor.solaredge_local_i1_m1_ac_energy_imported
• Einspeisung: sensor.solaredge_local_i1_m1_ac_energy_exported
• Batterie geladen: sensor.solaredge_local_i1_b1_energy_import
• Batterie entladen: sensor.solaredge_local_i1_b1_energy_export
• Batterie-SoC: sensor.solaredge_local_i1_b1_state_of_energy

Nach der Integration wurde ein HA-native Backup erzeugt und tar-geprueft: /mnt/user/appdata/homeassistant/backups/Custom_backup_2026.6.1_2026-06-13_14.59_48645373.tar.

Trade-off: Dieser Pfad ist lokal und liefert Inverter, Meter und Batterie ohne Cloud-API, nutzt aber eine Custom-Integration. Bei HA-Core-Upgrades auf Warnungen zu solaredge_modbus_multi achten.

10. Energy Dashboard

Status 2026-06-13: Energy Dashboard ist ueber die Home-Assistant-WebSocket-API konfiguriert und validiert.

Konfiguration:

• Netz: Bezug sensor.solaredge_local_i1_m1_ac_energy_imported, Einspeisung sensor.solaredge_local_i1_m1_ac_energy_exported
• PV: Produktion sensor.solaredge_local_i1_ac_energy, Live-Leistung sensor.solaredge_local_i1_ac_power
• Speicher: Entladung sensor.solaredge_local_i1_b1_energy_export, Ladung sensor.solaredge_local_i1_b1_energy_import, SoC sensor.solaredge_local_i1_b1_state_of_energy
• Kosten/Preise: noch nicht gesetzt; folgt mit Tibber

Verifikation:

TOKEN=$(cat /mnt/user/appdata/secrets/ha_token_codex)
# WebSocket: energy/get_prefs und energy/validate
sed -n '1,260p' /mnt/user/appdata/homeassistant/.storage/energy

Erwartung: .storage/energy enthaelt drei Quellen (grid, solar, battery), und energy/validate meldet keine Issues.

Nach der Energy-Konfiguration wurde ein HA-native Backup erzeugt und tar-geprueft: /mnt/user/appdata/homeassistant/backups/Custom_backup_2026.6.1_2026-06-13_15.59_25670583.tar.

Naechster Schritt: Tibber per HA-UI-Config-Flow verbinden und danach Kosten im Energy Dashboard ergaenzen.