oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Add CHELSTY home automation inventory model #2

Merged
oskar merged 1 commit from chelsty-home-automation into master 2026-05-11 13:27:59 +02:00
Conversation 0 Commits 1 Files changed 6 +319 -1
6 changed files with 319 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
docs/deployment.md
View file

@ -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.**

41
docs/topology.md
View file

@ -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.

57
hosts/chelsty/networking.yaml Normal file
View file

@ -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.

48
hosts/chelsty/paths.yaml Normal file
View file

@ -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.

108
hosts/chelsty/services.yaml Normal file
View file

@ -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.

14
inventory/topology.yaml
View file

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