2026-05-10 22:05:16 +02:00
|
|
|
# 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 |
|
2026-05-11 13:26:23 +02:00
|
|
|
| CHELSTY | LTE-connected edge hypervisor and Home Assistant node |
|
2026-05-10 22:05:16 +02:00
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
2026-05-11 13:26:23 +02:00
|
|
|
## 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.
|
|
|
|
|
|
2026-05-10 22:05:16 +02:00
|
|
|
## Runtime Layout
|
|
|
|
|
|
|
|
|
|
Runtime data should live under:
|
|
|
|
|
|
|
|
|
|
/opt/homelab
|
|
|
|
|
|
|
|
|
|
with separated:
|
|
|
|
|
- services
|
|
|
|
|
- data
|
|
|
|
|
- config
|
|
|
|
|
- logs
|
2026-05-11 13:26:23 +02:00
|
|
|
|
|
|
|
|
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.
|
