# 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

```sh
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

```sh
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:

```sh
docker network inspect frontend_net
```

## 3. Mosquitto vorbereiten

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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.