oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/docs/chelsty-runtime.md

1.9 KiB
Raw Permalink Blame History

CHELSTY Runtime

This document describes the runtime environment and deployment flow for CHELSTY, an offline-capable home automation edge node.

Runtime Layout

The CHELSTY runtime is located at /opt/homelab.

  • /opt/homelab/config/: Service-specific configurations and compose overrides.
  • /opt/homelab/data/: Persistent data for services.
  • /opt/homelab/logs/: Service logs.

Key Service Locations

  • Mosquitto: /opt/homelab/config/mosquitto/
  • Zigbee2MQTT: /opt/homelab/config/zigbee2mqtt/

SLZB-06U Integration

CHELSTY uses a SMLIGHT SLZB-06U Zigbee coordinator connected via Ethernet/TCP.

  • Coordinator IP: 192.168.1.105
  • Port: 6638
  • Protocol: TCP (ezsp adapter)

Zigbee2MQTT is configured to connect to this coordinator over the local network.

Offline & LTE Assumptions

  • WAN Resilience: All core automation (Zigbee, MQTT) runs locally on CHELSTY.
  • Connectivity: LTE provides intermittent uplink for remote management and Tailscale access.
  • Home Assistant: Runs in a separate VM, connecting to the Mosquitto broker on CHELSTY.

Deployment Flow

  1. Initial Bootstrap: Run the bootstrap script on the CHELSTY node:

    ./scripts/bootstrap/chelsty-runtime.sh

  2. Manual Configuration:

    • Edit /opt/homelab/config/zigbee2mqtt/.env with MQTT credentials.
    • Add Mosquitto user: 
      sudo mosquitto_passwd -b /opt/homelab/data/mosquitto/config/password.txt <user> <password>

  3. Service Deployment: Use the staged deployment runtime:

    ./scripts/deploy/deploy-node.sh chelsty

Recovery Procedure

In case of runtime failure:

  1. Verify Docker and Compose plugin: docker compose version
  2. Re-run bootstrap script to ensure directory structure and basic configs.
  3. Check Mosquitto logs: tail -f /opt/homelab/data/mosquitto/log/mosquitto.log
  4. Verify SLZB-06U reachability: ping 192.168.1.105