d59814c8fe
- 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
102 lines
2.8 KiB
Markdown
102 lines
2.8 KiB
Markdown
# 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
|
|
|
|
1. 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):
|
|
|
|
```bash
|
|
cp -n .env.sample .env # run from the repository root
|
|
```
|
|
|
|
2. Set the required values in the root `.env`:
|
|
|
|
```dotenv
|
|
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.
|
|
|
|
3. Render configs and generate Compose:
|
|
|
|
```bash
|
|
./setup-homeassistant.sh
|
|
```
|
|
|
|
4. Validate and start the stack:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.homeassistant.yml config --quiet
|
|
docker compose -f docker-compose.homeassistant.yml up -d
|
|
```
|
|
|
|
5. Verify the containers and open `http://<HOST_IP>:8123`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.homeassistant.yml exec zigbee2mqtt \
|
|
cat /app/data/configuration.yaml
|
|
```
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
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/`.
|