oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/docs/topology.md
Oskar Kapala d986a419f2 Add CHELSTY home automation inventory model
2026-05-11 13:26:23 +02:00

2.3 KiB
Raw Blame History

Homelab Topology

Nodes

Node Role
SATURN Control and development node
PIHA Infrastructure and monitoring node
SOLARIA AI and compute node
VPS Public ingress and edge node
CHELSTY LTE-connected edge hypervisor and Home Assistant node

Architecture Principles

  • Git is the source of truth.
  • SATURN is the primary orchestration and commit node.
  • Runtime state lives outside repositories.
  • Tailscale provides internal mesh networking.
  • Docker Compose remains the deployment model.
  • Public ingress is centralized on VPS.
  • 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:

/opt/homelab

with separated:

  • services
  • 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.