# 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/`.