docs: compress CLAUDE.md + fix zigbee2mqtt coordinator docs
- CLAUDE.md: collapsed 5-section deployment block to single annotated block, removed inline emit_event signatures (kept path + type list), flattened runtime path tree to bullets, condensed node table note to reference capabilities.yaml, added CHELSTY docker-compose v1 constraint; 156 → 113 lines (~750 → ~480 tokens) - fix: zigbee2mqtt/README.md updated to TCP coordinator (SLZB-06U at 192.168.1.105:6638, ezsp); removed stale /dev/ttyACM0 USB reference and corrected owner node from piha to chelsty-infra Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
20f6761a67
commit
f41ec5d0c5
87
CLAUDE.md
87
CLAUDE.md
|
|
@ -17,43 +17,22 @@ GitOps-lite orchestration for a distributed homelab. The repo is the source of t
|
|||
| **CHELSTY-INFRA** | LTE edge hypervisor (site: chelsty); Zigbee2MQTT, Mosquitto, stability-agent — offline-first |
|
||||
| **CHELSTY-HA** | LTE Home Assistant VM (site: chelsty); connects to CHELSTY-INFRA MQTT broker — offline-first |
|
||||
|
||||
All nodes communicate over Tailscale. CHELSTY-INFRA and CHELSTY-HA have an intermittent LTE uplink; their services (`zigbee2mqtt`, `mosquitto`, `homeassistant`, `stability-agent`) must never depend on SATURN, VPS, or Forgejo at runtime.
|
||||
All nodes communicate over Tailscale. CHELSTY-INFRA and CHELSTY-HA have an intermittent LTE uplink; their services must never depend on SATURN, VPS, or Forgejo at runtime. Full node capabilities: `hosts/<node>/capabilities.yaml`.
|
||||
|
||||
## Deployment
|
||||
|
||||
### Run a fresh deployment on the current node
|
||||
```bash
|
||||
scripts/deploy/deploy.sh
|
||||
scripts/deploy/deploy.sh # fresh deploy on current node
|
||||
scripts/deploy/deploy.sh --resume # resume after interruption
|
||||
scripts/deploy/deploy.sh --stage verify # specific stage only
|
||||
scripts/deploy/deploy.sh --service mosquitto # specific service only
|
||||
./scripts/deploy/deploy-control-plane.sh --ssh # SATURN/SOLARIA → VPS
|
||||
./scripts/deploy/deploy-node.sh chelsty-infra # CHELSTY nodes (individually)
|
||||
./scripts/bootstrap/prepare-node.sh # general node bootstrap
|
||||
./scripts/bootstrap/chelsty-runtime.sh # CHELSTY-specific bootstrap
|
||||
```
|
||||
|
||||
### Resume after interruption
|
||||
```bash
|
||||
scripts/deploy/deploy.sh --resume
|
||||
```
|
||||
|
||||
### Run a specific stage only
|
||||
```bash
|
||||
scripts/deploy/deploy.sh --stage verify
|
||||
scripts/deploy/deploy.sh --stage diagnose
|
||||
```
|
||||
|
||||
### Deploy a specific service
|
||||
```bash
|
||||
scripts/deploy/deploy.sh --service mosquitto
|
||||
```
|
||||
|
||||
### Deploy from SATURN/SOLARIA to VPS (control plane)
|
||||
```bash
|
||||
./scripts/deploy/deploy-control-plane.sh --ssh
|
||||
```
|
||||
|
||||
### Bootstrap a new node
|
||||
```bash
|
||||
./scripts/bootstrap/chelsty-runtime.sh # CHELSTY-specific
|
||||
./scripts/bootstrap/prepare-node.sh # General node prep
|
||||
```
|
||||
|
||||
The staged deploy pipeline runs: **prepare → validate → deploy → verify → diagnose (on failure) → complete**. Stage state is persisted in `/opt/homelab/state/deploy/` allowing safe resumption.
|
||||
Pipeline stages: **prepare → validate → deploy → verify → diagnose (on failure) → complete**. Stage state persisted in `/opt/homelab/state/deploy/`.
|
||||
|
||||
## Service Structure
|
||||
|
||||
|
|
@ -94,22 +73,9 @@ Agents must never execute destructive actions (restarts, deploys, config changes
|
|||
|
||||
## Event System
|
||||
|
||||
Events are append-only JSON lines at:
|
||||
```
|
||||
/opt/homelab/events/YYYY-MM-DD/<node>/events.jsonl
|
||||
```
|
||||
Events are append-only JSON lines at `/opt/homelab/events/YYYY-MM-DD/<node>/events.jsonl`.
|
||||
|
||||
Emit from shell:
|
||||
```bash
|
||||
source scripts/lib/events.sh
|
||||
emit_event "deployment_started" "info" "my-script.sh" "mosquitto" "cid-123" '{}'
|
||||
```
|
||||
|
||||
Emit from Python:
|
||||
```python
|
||||
from scripts.lib.events import emit_event
|
||||
emit_event("service_unhealthy", "error", "monitor.py", "ollama", "cid-123", {"error": "OOM"})
|
||||
```
|
||||
Emit via `scripts/lib/events.sh` (shell) or `scripts/lib/events.py` (Python).
|
||||
|
||||
Normalized event types: `deployment_started/completed/failed`, `service_unhealthy/recovered`, `node_offline/online`, `healthcheck_failed`, `remediation_started/completed`.
|
||||
|
||||
|
|
@ -124,29 +90,20 @@ When exploring the system, use these files in order:
|
|||
## CHELSTY-Specific Rules
|
||||
|
||||
- Zigbee coordinator is **SLZB-06U** over TCP (`192.168.1.105:6638`, `ezsp` adapter). Never use `/dev/ttyUSB0`.
|
||||
- Deploy CHELSTY nodes individually:
|
||||
```bash
|
||||
./scripts/deploy/deploy-node.sh chelsty-infra
|
||||
./scripts/deploy/deploy-node.sh chelsty-ha
|
||||
```
|
||||
- Bootstrap CHELSTY runtime:
|
||||
```bash
|
||||
./scripts/bootstrap/chelsty-runtime.sh
|
||||
```
|
||||
- CHELSTY nodes run **docker-compose v1** (1.29.2) — use `docker-compose` (hyphenated), not `docker compose`.
|
||||
- Critical backup sets: HA config+data, Zigbee2MQTT config+db+network key, Mosquitto config+persistence, SLZB-06U coordinator state.
|
||||
|
||||
## Runtime Path Conventions
|
||||
|
||||
```
|
||||
/opt/homelab/
|
||||
├── data/<service>/ # Persistent volumes
|
||||
├── config/<service>/ # Secrets and host-local overrides (not in Git)
|
||||
├── logs/<service>/ # Service logs
|
||||
├── state/ # Deployment stage markers, agent heartbeats
|
||||
├── events/ # Append-only event store
|
||||
├── world/ # Observer output (synthesized state)
|
||||
└── actions/ # pending / approved / running / completed / failed
|
||||
```
|
||||
`/opt/homelab/` layout on each node:
|
||||
|
||||
- `data/<service>/` — persistent volumes
|
||||
- `config/<service>/` — secrets and host-local overrides (not in Git)
|
||||
- `logs/<service>/` — service logs
|
||||
- `state/` — deployment stage markers, agent heartbeats
|
||||
- `events/` — append-only event store
|
||||
- `world/` — Observer output (synthesized state)
|
||||
- `actions/` — pending / approved / running / completed / failed
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,10 @@
|
|||
Zigbee to MQTT bridge, get rid of your proprietary Zigbee bridges.
|
||||
|
||||
## Usage
|
||||
Deployed on the `piha` node.
|
||||
|
||||
Requires a Zigbee adapter (e.g., Sonoff ZBDongle-E) mapped to `/dev/ttyACM0`.
|
||||
Deployed on the `chelsty-infra` node (CHELSTY site).
|
||||
|
||||
Coordinator: **SLZB-06U** over TCP at `192.168.1.105:6638` (`ezsp` adapter).
|
||||
Do not use USB paths (`/dev/ttyUSB0`, `/dev/ttyACM0`) — the coordinator is network-attached.
|
||||
|
||||
Frontend is available on port 8080.
|
||||
|
|
|
|||
Loading…
Reference in a new issue