Merge pull request 'Add CHELSTY home automation inventory model' (#2) from chelsty-home-automation into master

Reviewed-on: #2

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/<service>/`.
 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.**

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/<service>` for persistent service data.
+- `/opt/homelab/config/<service>` for host-local configuration and secrets.
+- `/opt/homelab/logs/<service>` 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.

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.

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.

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.

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