5b9111afa7
ken is HAOS (no SSH/docker exec path), so it needs a REST/WebSocket-only adapter: automations/scripts/scenes via one GET per /api/config/<domain>/config/<id>, dashboards/area+entity registries/ input_* helpers via the HA WebSocket API (read-only commands only). scripts/ha/lib/ha_api.py and ha_ws.py never take a token as a value — only a token_path, read from disk in-process — so the bearer token never touches a subprocess argv or a log line. ha_ws.py depends on the optional websocket-client package and raises a clear, actionable ImportError if it's missing rather than a raw traceback; import.sh still completes the REST-only part of the import in that case. Automations/scripts/scenes reuse split.write_split() so both adapters produce byte-identical config/<instance>/ layouts and the same idempotent stale-file cleanup on re-run. docker-exec adapter logic is untouched.
103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# home-assistant (configs-as-code)
|
|
|
|
**Status: skeleton.** Structure and read-only import tooling only — no
|
|
deploy path exists yet. See `DESIGN.md` for the full phasing, adapter, sync,
|
|
and validation model, and for the open questions still blocking phase 2/3.
|
|
|
|
## Layout
|
|
|
|
```
|
|
services/home-assistant/
|
|
├── DESIGN.md # decision registry — read this first
|
|
├── instances.yaml # per-instance adapter/host/token config
|
|
├── .gitignore # excludes secrets/db/log/token paths from every import
|
|
├── config/<instance>/ # canonical, normalized /config mirror per instance
|
|
├── storage-export/<instance>/ # curated .storage/* export (registries, dashboards)
|
|
└── fixtures/ # dated /api/states snapshots
|
|
```
|
|
|
|
Instances: `ken` (RPi4/HAOS, LAN 192.168.31.7, api adapter — canonical home
|
|
instance since the 2026-07-22 cutover), `ken-legacy` (PIHA, container
|
|
`homeassistant5`, docker-exec adapter, archived — pre-migration instance,
|
|
import only, never deploy), `chelsty-ha` (Tailscale, api adapter — see
|
|
`instances.yaml` and `DESIGN.md` "Incident log").
|
|
|
|
## Import
|
|
|
|
```bash
|
|
scripts/ha/import.sh ken
|
|
scripts/ha/import.sh ken-legacy
|
|
```
|
|
|
|
Read-only, and idempotent for both adapters — re-running against an
|
|
unchanged instance produces no diff.
|
|
|
|
**`docker-exec` adapter** (`ken-legacy`): pulls the whole `/config` tree
|
|
over `ssh ... docker exec ... tar`, filters it through `.gitignore`,
|
|
normalizes and splits it into `config/<instance>/`, exports curated
|
|
`.storage/*` into `storage-export/<instance>/`.
|
|
|
|
**`api` adapter** (`ken`, `chelsty-ha`): for instances with no
|
|
filesystem/SSH access (HAOS has none). Pulls automations/scripts/scenes via
|
|
one REST GET per object (`/api/config/<domain>/config/<id>`) and
|
|
dashboards/area+entity registries/`input_*` helpers via the WebSocket API
|
|
(`/api/websocket`) — read-only commands only, nothing that mutates the live
|
|
instance. Full `/config` import is out of scope for this adapter; see
|
|
DESIGN.md, "Deploy path: adapter per instance".
|
|
|
|
Both adapters also write a dated `/api/states` fixture snapshot to
|
|
`fixtures/` if a deploy token exists at
|
|
`~/.config/ha-deploy/<instance>.token`. For the `api` adapter, that token is
|
|
not optional — see "Tokens" below.
|
|
|
|
### Tokens
|
|
|
|
The `api` adapter has no filesystem fallback, so a missing or empty token
|
|
at `token_path` (see `instances.yaml`) is a hard error, not a soft-skip —
|
|
`import.sh` aborts immediately with a clear message rather than silently
|
|
producing an empty import. See `DESIGN.md`, "Tokens", for how the
|
|
`deploy_agent` account and its long-lived access token are provisioned.
|
|
|
|
The token itself never touches a subprocess argv or a log line: REST calls
|
|
go through `scripts/ha/lib/ha_api.py`, which reads the token file itself and
|
|
sets the `Authorization` header in-process via `requests` (never `curl -H`,
|
|
which would put the token in that process's argv, visible to any local user
|
|
via `ps`). `requests` (`python3-requests`) is a very common preinstalled/
|
|
transitive package on Debian-based nodes; if it's ever missing, `import.sh`
|
|
fails with Python's own `ModuleNotFoundError` — install it the same way as
|
|
`python3-websocket` below (`sudo apt install python3-requests` or `pip
|
|
install --user requests`).
|
|
|
|
### WebSocket dependency
|
|
|
|
The dashboard/registry/helper export (`scripts/ha/lib/ha_ws.py`) depends on
|
|
the `websocket-client` PyPI package (import name `websocket`) — not in the
|
|
stdlib, not installed by default. Install one of:
|
|
|
|
```bash
|
|
sudo apt install python3-websocket # Debian/Ubuntu package name
|
|
# or
|
|
pip install --user websocket-client
|
|
```
|
|
|
|
If it's missing, `import.sh ken` still imports automations/scripts/scenes
|
|
(REST-only, no extra dependency needed) and then reports the
|
|
dashboards/registries/helpers step as skipped with an actionable message
|
|
naming the package to install — it does not crash with a raw traceback, and
|
|
it does not silently produce an incomplete `storage-export/` without saying
|
|
so.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
scripts/ha/tests/test_split_normalize.sh
|
|
scripts/ha/tests/test_normalize_tags.sh
|
|
scripts/ha/tests/test_import_api_offline.sh
|
|
```
|
|
|
|
All offline — no network, no HA instance required. `test_import_api_offline.sh`
|
|
covers the `api` adapter: normalization of real-shaped API responses (saved
|
|
as fixtures under `tests/fixtures/`), idempotency, stale-file cleanup, and
|
|
the missing-`websocket-client` error path (via `sys.modules` injection, not
|
|
an actual network call).
|