# 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-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

Naechster Schritt nach der Foundation: HA-MQTT-Integration im UI mit Broker
`smarthome-mosquitto:1883` verbinden und danach per API/Log pruefen.