From d986a419f2aba608a15fee506723f7953c3c4fc9 Mon Sep 17 00:00:00 2001 From: Oskar Kapala Date: Mon, 11 May 2026 13:26:23 +0200 Subject: [PATCH] Add CHELSTY home automation inventory model --- docs/deployment.md | 52 ++++++++++++++++ docs/topology.md | 41 ++++++++++++- hosts/chelsty/networking.yaml | 57 ++++++++++++++++++ hosts/chelsty/paths.yaml | 48 +++++++++++++++ hosts/chelsty/services.yaml | 108 ++++++++++++++++++++++++++++++++++ inventory/topology.yaml | 14 +++++ 6 files changed, 319 insertions(+), 1 deletion(-) create mode 100644 hosts/chelsty/networking.yaml create mode 100644 hosts/chelsty/paths.yaml create mode 100644 hosts/chelsty/services.yaml diff --git a/docs/deployment.md b/docs/deployment.md index 6f28206..6431cc2 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -8,6 +8,7 @@ This document describes the GitOps-lite deployment process for the homelab. 2. **Unidirectional Flow**: Changes flow from **SATURN** (commit node) to execution nodes. 3. **Lightweight**: No complex orchestrators (no Kubernetes). Use `docker compose` and simple shell scripts. 4. **Tailscale Mesh**: All hosts are connected via Tailscale, allowing secure communication without public port exposure. +5. **Host Autonomy**: Services that must operate during WAN or Git outages keep their runtime dependencies on the execution node or local LAN. ## Deployment Process @@ -33,6 +34,57 @@ If a service requires host-specific configuration (e.g., unique device paths for 1. Create a `docker-compose.override.yml` in `/opt/homelab/config//`. 2. The deployment script should include this override if it exists. +For CHELSTY Home Assistant infrastructure, host-local configuration is the +authority for runtime identity, secrets, and local device endpoints: + +- Home Assistant config: `/opt/homelab/config/homeassistant` +- Zigbee2MQTT config: `/opt/homelab/config/zigbee2mqtt` +- Mosquitto config: `/opt/homelab/config/mosquitto` + +CHELSTY services must not require SATURN, VPS, or Forgejo to be reachable after +deployment has completed. Docker Compose definitions can still come from Git, +but Home Assistant automation, Zigbee control, and MQTT messaging must continue +locally while LTE or Tailscale connectivity is unavailable. + +## Exposure Classes + +Service inventory may declare one of these exposure classes: + +- `local-only`: bind only to host, LAN, or container networks. This is the default for Zigbee2MQTT and Mosquitto. +- `tailscale-internal`: reachable over Tailscale only. This is appropriate for Home Assistant remote administration. +- `public`: reachable from the public internet through a deliberate ingress path, normally the VPS edge role. + +Public exposure is not implied by a service existing in Git. It must be explicit +in host inventory and ingress configuration. + +## CHELSTY Home Automation Deployment Notes + +CHELSTY remains a Docker Compose execution node. No Kubernetes, Helm, Ansible, +or additional orchestration layer is required for Home Assistant infrastructure. + +The SLZB-06U coordinator is network-connected over Ethernet or WiFi. Compose +files and host overrides should configure Zigbee2MQTT for a TCP/network +coordinator endpoint, not a USB serial device. Avoid `/dev/ttyUSB0` mappings. + +Runtime paths follow the standard layout: + +- `/opt/homelab/data/homeassistant` +- `/opt/homelab/config/homeassistant` +- `/opt/homelab/logs/homeassistant` +- `/opt/homelab/data/zigbee2mqtt` +- `/opt/homelab/config/zigbee2mqtt` +- `/opt/homelab/logs/zigbee2mqtt` +- `/opt/homelab/data/mosquitto` +- `/opt/homelab/config/mosquitto` +- `/opt/homelab/logs/mosquitto` + +Recommended backup coverage: + +- Home Assistant config and persistent data before upgrades or major integration changes. +- Zigbee2MQTT config, database, coordinator backup files, and Zigbee network key material. +- SLZB-06U firmware version, exported configuration, network address reservation, and coordinator state. +- Mosquitto config, ACL/password files, persistence data, and bridge configuration if enabled. + ## Secrets Management - **Do NOT commit secrets to Git.** diff --git a/docs/topology.md b/docs/topology.md index 5ace63f..31eb5c0 100644 --- a/docs/topology.md +++ b/docs/topology.md @@ -8,7 +8,7 @@ | PIHA | Infrastructure and monitoring node | | SOLARIA | AI and compute node | | VPS | Public ingress and edge node | -| CHELSTY | Virtualization and Home Assistant node | +| CHELSTY | LTE-connected edge hypervisor and Home Assistant node | ## Architecture Principles @@ -21,6 +21,36 @@ - Deployment uses lightweight shell scripts. - Avoid Kubernetes and heavy orchestration frameworks. +## CHELSTY Home Automation + +CHELSTY hosts the local home automation control plane. Because it uses an LTE +uplink and may be intermittently connected, Home Assistant, Zigbee2MQTT, and +Mosquitto must continue operating without SATURN, VPS, or Forgejo. + +The CHELSTY Home Assistant inventory is split across: + +- `hosts/chelsty/services.yaml` +- `hosts/chelsty/networking.yaml` +- `hosts/chelsty/paths.yaml` + +Service exposure is classified as: + +- `local-only`: available only on local host, LAN, or container networks. +- `tailscale-internal`: available to approved Tailscale clients only. +- `public`: available from the public internet through explicit ingress. + +Initial CHELSTY service intent: + +| Service | Role | Exposure | Offline required | +|---|---|---|---| +| homeassistant | Home automation controller | tailscale-internal | yes | +| zigbee2mqtt | Zigbee to MQTT bridge | local-only | yes | +| mosquitto | Local MQTT broker | local-only | yes | + +The Zigbee coordinator is an SLZB-06U network coordinator. It should be modeled +as an Ethernet/WiFi network device consumed by Zigbee2MQTT, not as a USB dongle. +Do not use `/dev/ttyUSB0` or other USB device mappings for this coordinator. + ## Runtime Layout Runtime data should live under: @@ -32,3 +62,12 @@ with separated: - data - config - logs + +CHELSTY follows the same layout: + +- `/opt/homelab/data/` for persistent service data. +- `/opt/homelab/config/` for host-local configuration and secrets. +- `/opt/homelab/logs/` for logs that should stay outside Git. + +Critical backup sets on CHELSTY include Home Assistant config, Zigbee2MQTT +config and network state, Mosquitto config/data, and SLZB-06U coordinator state. diff --git a/hosts/chelsty/networking.yaml b/hosts/chelsty/networking.yaml new file mode 100644 index 0000000..ca59ca6 --- /dev/null +++ b/hosts/chelsty/networking.yaml @@ -0,0 +1,57 @@ +host: chelsty + +uplink: + type: lte + connectivity: intermittent + public_reachability: not-assumed + +tailscale: + enabled: true + host_ip: 100.122.201.22 + role: internal-management + +exposure_classes: + local-only: + description: LAN, host, or container-network access only. + tailscale-internal: + description: Tailnet access only; no public ingress dependency. + public: + description: Public internet exposure through an explicitly defined ingress host. + +networks: + home_automation_lan: + purpose: Home Assistant, MQTT, Zigbee coordinator, and local device control. + offline_required: true + internet_required_for_core_operation: false + +devices: + slzb-06u: + role: zigbee-coordinator + vendor_model: SLZB-06U + connection_type: network + transport: + primary: ethernet + secondary: wifi + usb: false + address: + hostname: slzb-06u.local + ipv4: null + port: 6638 + protocol: tcp + consumers: + - zigbee2mqtt + placement: chelsty-home-automation-lan + operational_notes: + - Treat the coordinator as a network appliance, not a USB dongle. + - Do not configure /dev/ttyUSB0 or other host USB device mappings for this coordinator. + - Prefer static DHCP or a reserved IP once the LAN addressing plan is known. + backup: + recommended: true + include: + - coordinator firmware version + - coordinator configuration export + - Zigbee network backup from Zigbee2MQTT + - device IEEE address and network parameters + notes: + - Keep a copy of coordinator state with the Zigbee2MQTT backup set. + - Record the reserved IP or DNS name used by Zigbee2MQTT. diff --git a/hosts/chelsty/paths.yaml b/hosts/chelsty/paths.yaml new file mode 100644 index 0000000..59434f1 --- /dev/null +++ b/hosts/chelsty/paths.yaml @@ -0,0 +1,48 @@ +host: chelsty + +runtime_root: /opt/homelab + +conventions: + services: /opt/homelab/services + data: /opt/homelab/data + config: /opt/homelab/config + logs: /opt/homelab/logs + +services: + homeassistant: + data: /opt/homelab/data/homeassistant + config: /opt/homelab/config/homeassistant + logs: /opt/homelab/logs/homeassistant + backup_priority: critical + + zigbee2mqtt: + data: /opt/homelab/data/zigbee2mqtt + config: /opt/homelab/config/zigbee2mqtt + logs: /opt/homelab/logs/zigbee2mqtt + backup_priority: critical + + mosquitto: + data: /opt/homelab/data/mosquitto + config: /opt/homelab/config/mosquitto + logs: /opt/homelab/logs/mosquitto + backup_priority: high + +backup_sets: + homeassistant: + include: + - /opt/homelab/config/homeassistant + - /opt/homelab/data/homeassistant + restore_note: Restore before starting the Home Assistant container. + + zigbee2mqtt: + include: + - /opt/homelab/config/zigbee2mqtt + - /opt/homelab/data/zigbee2mqtt + restore_note: Restore before starting Zigbee2MQTT so coordinator and network state remain aligned. + + slzb-06u: + include: + - SLZB-06U firmware version + - SLZB-06U exported configuration + - Zigbee network backup generated by Zigbee2MQTT + restore_note: Restore or reconfigure coordinator state before permitting Zigbee2MQTT to reform the network. diff --git a/hosts/chelsty/services.yaml b/hosts/chelsty/services.yaml new file mode 100644 index 0000000..b7ee27e --- /dev/null +++ b/hosts/chelsty/services.yaml @@ -0,0 +1,108 @@ +host: chelsty + +exposure_classes: + local-only: + description: Reachable only from CHELSTY-local networks or container networks. + public_ingress: false + tailscale_required: false + tailscale-internal: + description: Reachable through the Tailscale mesh by approved tailnet clients. + public_ingress: false + tailscale_required: true + public: + description: Reachable from the public internet through an explicit ingress path. + public_ingress: true + tailscale_required: false + +operational_constraints: + uplink: lte + connectivity: intermittent + offline_operation_required: true + must_not_depend_on: + - saturn + - vps + - forgejo + +services: + homeassistant: + role: home-automation-controller + deployment_model: docker-compose + exposure: tailscale-internal + offline_required: true + depends_on: + local: + - mosquitto + - zigbee2mqtt + external: [] + ports: + - name: http + container_port: 8123 + protocol: tcp + runtime: + config_path: /opt/homelab/config/homeassistant + data_path: /opt/homelab/data/homeassistant + logs_path: /opt/homelab/logs/homeassistant + backup: + recommended: true + include: + - /opt/homelab/config/homeassistant + - /opt/homelab/data/homeassistant + notes: + - Back up before Home Assistant core, supervisor-equivalent, or integration upgrades. + - Keep local restore copies on CHELSTY because LTE connectivity may be unavailable during recovery. + + zigbee2mqtt: + role: zigbee-mqtt-bridge + deployment_model: docker-compose + exposure: local-only + offline_required: true + depends_on: + local: + - mosquitto + external: + - slzb-06u + coordinator: + name: slzb-06u + connection: network + usb_device: null + ports: + - name: frontend + container_port: 8080 + protocol: tcp + exposure: tailscale-internal + runtime: + config_path: /opt/homelab/config/zigbee2mqtt + data_path: /opt/homelab/data/zigbee2mqtt + logs_path: /opt/homelab/logs/zigbee2mqtt + backup: + recommended: true + include: + - /opt/homelab/config/zigbee2mqtt + - /opt/homelab/data/zigbee2mqtt + notes: + - Include configuration.yaml, database.db, coordinator backup files, and network key material. + - Restore Zigbee2MQTT state together with the SLZB-06U coordinator state when replacing hardware. + + mosquitto: + role: local-mqtt-broker + deployment_model: docker-compose + exposure: local-only + offline_required: true + depends_on: + local: [] + external: [] + ports: + - name: mqtt + container_port: 1883 + protocol: tcp + runtime: + config_path: /opt/homelab/config/mosquitto + data_path: /opt/homelab/data/mosquitto + logs_path: /opt/homelab/logs/mosquitto + backup: + recommended: true + include: + - /opt/homelab/config/mosquitto + - /opt/homelab/data/mosquitto + notes: + - Retain ACL, password, persistence, and bridge configuration if enabled. diff --git a/inventory/topology.yaml b/inventory/topology.yaml index d430507..c5adabd 100644 --- a/inventory/topology.yaml +++ b/inventory/topology.yaml @@ -30,6 +30,20 @@ nodes: chelsty: roles: + - remote - hypervisor - homeassistant - staging + connectivity: + uplink: lte + intermittent: true + home_automation: + offline_operation_required: true + services: + - homeassistant + - zigbee2mqtt + - mosquitto + coordinator: + model: SLZB-06U + connection: network + usb: false