homelab-blueprint/docker-compose-files/homeassistant

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):

   cp -n .env.sample .env   # run from the repository root
   

2. 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.

3. Render configs and generate Compose:

   ./setup-homeassistant.sh
   

4. Validate and start the stack:

   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:

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