Brian Pooe d59814c8fe fix(homeassistant): harden blueprint for fresh installs and public repo safety

- Add SLZB06_HOST and CADDY_HOST_IP stubs to root .env.sample so cp -n covers all required vars
- Remove dead :-10.0.15.5 default from ha_configuration.yaml (CADDY_HOST_IP is required; default was unreachable)
- Genericise CADDY_HOST_IP comment in ha_configuration.yaml (removed hardcoded personal IP)
- Default zigbee2mqtt pan_id and network_key to GENERATE (remove personal network credentials from public blueprint)
- Remove hardcoded device list from zigbee2mqtt_configuration.yaml (Z2M builds this on pairing)
- Clarify README installation steps: root .env path, missing-var behaviour for SLZB06_HOST and CADDY_HOST_IP

2026-06-27 17:38:04 +02:00

2.8 KiB

Raw Blame History

Home Assistant

Docker deployment for Home Assistant, Mosquitto, and Zigbee2MQTT. Run all commands from the repository root.

Persistent Data

Home Assistant and Mosquitto runtime state use the Docker-managed named volumes homeassistant_data, mqtt_data, and mqtt_log. Their generated configuration files remain read-only host mounts under appdata/.

Zigbee2MQTT live configuration, coordinator backup, and device database use the zigbee2mqtt_data named volume. Existing bind-mount deployments must migrate Home Assistant, Mosquitto, and Zigbee2MQTT state into the named volumes before recreating the stack.

Installation

Create the root .env from the sample if it does not exist, then fill in all required values (the sample has stubs for every variable below):
```
cp -n .env.sample .env   # run from the repository root
```
Set the required values in the root .env:
```
TZ=Africa/Johannesburg
SLZB06_HOST=<zigbee-coordinator-ip>
CADDY_HOST_IP=<caddy-container-host-ip>
DOCKERLOGGING_MAXFILE=3
DOCKERLOGGING_MAXSIZE=10m
```
SLZB06_HOST and CADDY_HOST_IP are Home Assistant-specific and have no defaults — the setup script will abort if either is missing.
Render configs and generate Compose:
```
./setup-homeassistant.sh
```

Validate and start the stack:

docker compose -f docker-compose.homeassistant.yml config --quiet
docker compose -f docker-compose.homeassistant.yml up -d

Verify the containers and open http://<HOST_IP>:8123:

docker compose -f docker-compose.homeassistant.yml ps
docker compose -f docker-compose.homeassistant.yml logs --tail=100

Apply Configuration Changes

Run the setup script after changing .env or source templates, then recreate the stack:

./setup-homeassistant.sh
docker compose -f docker-compose.homeassistant.yml up -d

The script preserves an existing Zigbee2MQTT configuration.yaml in the named volume.

Initial Setup

Complete Home Assistant onboarding, then verify MQTT and Zigbee2MQTT. Open the Zigbee2MQTT frontend at http://<HOST_IP>:8080.

Network Requirements

The host must reach the SLZB-06U coordinator on TCP port 6638.
Trusted clients or Caddy need access to Home Assistant and Zigbee2MQTT.

Troubleshooting

Check the Zigbee2MQTT live configuration and coordinator address if it cannot connect:

docker compose -f docker-compose.homeassistant.yml exec zigbee2mqtt \
  cat /app/data/configuration.yaml

Useful Commands

docker compose -f docker-compose.homeassistant.yml restart homeassistant

Backup

Back up the homeassistant_data, mqtt_data, mqtt_log, and zigbee2mqtt_data named volumes plus the generated configuration files under appdata/.

2.8 KiB Raw Blame History