docker.recipes

Home Assistant Smart Home Hub

intermediate

Complete smart home automation with Home Assistant, MQTT, and Zigbee support.

Overview

Home Assistant is an open-source home automation platform that prioritizes local control and privacy while integrating with over 2000 smart home devices and services. Originally created by Paulus Schoutsen in 2013, it has grown into the most popular self-hosted home automation solution, offering powerful automation engines, custom dashboards, and extensive device support without relying on cloud services or proprietary hubs. This comprehensive smart home stack combines Home Assistant with essential supporting services: Mosquitto MQTT broker for lightweight device messaging, Zigbee2MQTT for direct Zigbee device control without proprietary hubs, MariaDB for reliable configuration and state storage, InfluxDB for long-term sensor data retention, and Grafana for advanced analytics and visualization. Together, these components create a complete local smart home ecosystem that can handle everything from simple light switches to complex multi-sensor automation scenarios. This stack is ideal for privacy-conscious homeowners, smart home enthusiasts who want full local control, and home lab operators building comprehensive IoT infrastructures. Unlike cloud-dependent solutions like SmartThings or Alexa, this combination keeps all data and processing local while providing enterprise-grade monitoring and analytics capabilities typically found in industrial IoT deployments.

Key Features

  • 2000+ device integrations including Philips Hue, IKEA TRADFRI, Nest, and Sonos
  • Local Zigbee device control through dedicated coordinator without proprietary hubs
  • MQTT broker supporting lightweight pub/sub messaging for ESP32/Arduino projects
  • Advanced automation engine with state machines, triggers, and complex conditionals
  • Long-term sensor data retention with purpose-built time-series database storage
  • Professional-grade dashboard creation with 50+ visualization types and alerting
  • Voice assistant integration supporting custom wake words and offline processing
  • Energy monitoring with solar panel integration and usage tracking dashboards

Common Use Cases

  • 1Complete smart home automation with lights, thermostats, security cameras, and door locks
  • 2DIY IoT sensor networks using ESP32/Arduino devices with MQTT communication
  • 3Home energy monitoring with solar panel production and consumption analytics
  • 4Multi-protocol device integration combining Zigbee, Z-Wave, WiFi, and Bluetooth devices
  • 5Privacy-focused smart home avoiding cloud-dependent solutions like SmartThings or Wink
  • 6Home lab enthusiasts building comprehensive IoT data collection and visualization systems
  • 7Rental properties or apartments where residents want smart features without permanent modifications

Prerequisites

  • Minimum 2GB RAM recommended for Home Assistant with database integration
  • USB Zigbee coordinator stick (CC2531, CC2652P, or ConBee II) connected to host system
  • Ports 8123, 8080, 3000, 8086, and 1883 available for web interfaces and MQTT
  • Basic understanding of YAML configuration for Home Assistant automations and integrations
  • Knowledge of MQTT topics and payloads for custom device integration
  • /dev/ttyUSB0 device path accessible to Docker containers for Zigbee coordinator

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  homeassistant: 
3    image: ghcr.io/home-assistant/home-assistant:stable
4    volumes: 
5      - ha_config:/config
6      - /etc/localtime:/etc/localtime:ro
7    ports: 
8      - "8123:8123"
9    privileged: true
10    networks: 
11      - ha_net
12
13  mosquitto: 
14    image: eclipse-mosquitto:latest
15    ports: 
16      - "1883:1883"
17      - "9001:9001"
18    volumes: 
19      - mosquitto_config:/mosquitto/config
20      - mosquitto_data:/mosquitto/data
21      - mosquitto_log:/mosquitto/log
22    networks: 
23      - ha_net
24
25  zigbee2mqtt: 
26    image: koenkk/zigbee2mqtt:latest
27    volumes: 
28      - zigbee_data:/app/data
29      - /run/udev:/run/udev:ro
30    ports: 
31      - "8080:8080"
32    environment: 
33      - TZ=UTC
34    devices: 
35      - /dev/ttyUSB0:/dev/ttyUSB0
36    depends_on: 
37      - mosquitto
38    networks: 
39      - ha_net
40
41  mariadb: 
42    image: mariadb:10.11
43    environment: 
44      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
45      - MYSQL_DATABASE=homeassistant
46      - MYSQL_USER=homeassistant
47      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
48    volumes: 
49      - mariadb_data:/var/lib/mysql
50    networks: 
51      - ha_net
52
53  influxdb: 
54    image: influxdb:2.7
55    ports: 
56      - "8086:8086"
57    environment: 
58      - DOCKER_INFLUXDB_INIT_MODE=setup
59      - DOCKER_INFLUXDB_INIT_USERNAME=admin
60      - DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
61      - DOCKER_INFLUXDB_INIT_ORG=homelab
62      - DOCKER_INFLUXDB_INIT_BUCKET=homeassistant
63    volumes: 
64      - influxdb_data:/var/lib/influxdb2
65    networks: 
66      - ha_net
67
68  grafana: 
69    image: grafana/grafana:latest
70    ports: 
71      - "3000:3000"
72    environment: 
73      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
74    volumes: 
75      - grafana_data:/var/lib/grafana
76    networks: 
77      - ha_net
78
79volumes: 
80  ha_config: 
81  mosquitto_config: 
82  mosquitto_data: 
83  mosquitto_log: 
84  zigbee_data: 
85  mariadb_data: 
86  influxdb_data: 
87  grafana_data: 
88
89networks: 
90  ha_net:

.env Template

.env
1# Home Assistant
2MYSQL_ROOT_PASSWORD=secure_root_password
3MYSQL_PASSWORD=secure_mysql_password
4INFLUXDB_PASSWORD=secure_influxdb_password
5GRAFANA_PASSWORD=secure_grafana_password
6
7# Home Assistant at http://localhost:8123
8# Zigbee2MQTT at http://localhost:8080
9# Grafana at http://localhost:3000

Usage Notes

  1. 1Home Assistant at http://localhost:8123
  2. 2Zigbee2MQTT at http://localhost:8080
  3. 3Configure Zigbee adapter device path
  4. 4MQTT broker for device communication
  5. 5InfluxDB for long-term history

Individual Services(6 services)

Copy individual services to mix and match with your existing compose files.

homeassistant
homeassistant:
  image: ghcr.io/home-assistant/home-assistant:stable
  volumes:
    - ha_config:/config
    - /etc/localtime:/etc/localtime:ro
  ports:
    - "8123:8123"
  privileged: true
  networks:
    - ha_net
mosquitto
mosquitto:
  image: eclipse-mosquitto:latest
  ports:
    - "1883:1883"
    - "9001:9001"
  volumes:
    - mosquitto_config:/mosquitto/config
    - mosquitto_data:/mosquitto/data
    - mosquitto_log:/mosquitto/log
  networks:
    - ha_net
zigbee2mqtt
zigbee2mqtt:
  image: koenkk/zigbee2mqtt:latest
  volumes:
    - zigbee_data:/app/data
    - /run/udev:/run/udev:ro
  ports:
    - "8080:8080"
  environment:
    - TZ=UTC
  devices:
    - /dev/ttyUSB0:/dev/ttyUSB0
  depends_on:
    - mosquitto
  networks:
    - ha_net
mariadb
mariadb:
  image: mariadb:10.11
  environment:
    - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
    - MYSQL_DATABASE=homeassistant
    - MYSQL_USER=homeassistant
    - MYSQL_PASSWORD=${MYSQL_PASSWORD}
  volumes:
    - mariadb_data:/var/lib/mysql
  networks:
    - ha_net
influxdb
influxdb:
  image: influxdb:2.7
  ports:
    - "8086:8086"
  environment:
    - DOCKER_INFLUXDB_INIT_MODE=setup
    - DOCKER_INFLUXDB_INIT_USERNAME=admin
    - DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
    - DOCKER_INFLUXDB_INIT_ORG=homelab
    - DOCKER_INFLUXDB_INIT_BUCKET=homeassistant
  volumes:
    - influxdb_data:/var/lib/influxdb2
  networks:
    - ha_net
grafana
grafana:
  image: grafana/grafana:latest
  ports:
    - "3000:3000"
  environment:
    - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
  volumes:
    - grafana_data:/var/lib/grafana
  networks:
    - ha_net

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  homeassistant:
5    image: ghcr.io/home-assistant/home-assistant:stable
6    volumes:
7      - ha_config:/config
8      - /etc/localtime:/etc/localtime:ro
9    ports:
10      - "8123:8123"
11    privileged: true
12    networks:
13      - ha_net
14
15  mosquitto:
16    image: eclipse-mosquitto:latest
17    ports:
18      - "1883:1883"
19      - "9001:9001"
20    volumes:
21      - mosquitto_config:/mosquitto/config
22      - mosquitto_data:/mosquitto/data
23      - mosquitto_log:/mosquitto/log
24    networks:
25      - ha_net
26
27  zigbee2mqtt:
28    image: koenkk/zigbee2mqtt:latest
29    volumes:
30      - zigbee_data:/app/data
31      - /run/udev:/run/udev:ro
32    ports:
33      - "8080:8080"
34    environment:
35      - TZ=UTC
36    devices:
37      - /dev/ttyUSB0:/dev/ttyUSB0
38    depends_on:
39      - mosquitto
40    networks:
41      - ha_net
42
43  mariadb:
44    image: mariadb:10.11
45    environment:
46      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
47      - MYSQL_DATABASE=homeassistant
48      - MYSQL_USER=homeassistant
49      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
50    volumes:
51      - mariadb_data:/var/lib/mysql
52    networks:
53      - ha_net
54
55  influxdb:
56    image: influxdb:2.7
57    ports:
58      - "8086:8086"
59    environment:
60      - DOCKER_INFLUXDB_INIT_MODE=setup
61      - DOCKER_INFLUXDB_INIT_USERNAME=admin
62      - DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
63      - DOCKER_INFLUXDB_INIT_ORG=homelab
64      - DOCKER_INFLUXDB_INIT_BUCKET=homeassistant
65    volumes:
66      - influxdb_data:/var/lib/influxdb2
67    networks:
68      - ha_net
69
70  grafana:
71    image: grafana/grafana:latest
72    ports:
73      - "3000:3000"
74    environment:
75      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
76    volumes:
77      - grafana_data:/var/lib/grafana
78    networks:
79      - ha_net
80
81volumes:
82  ha_config:
83  mosquitto_config:
84  mosquitto_data:
85  mosquitto_log:
86  zigbee_data:
87  mariadb_data:
88  influxdb_data:
89  grafana_data:
90
91networks:
92  ha_net:
93EOF
94
95# 2. Create the .env file
96cat > .env << 'EOF'
97# Home Assistant
98MYSQL_ROOT_PASSWORD=secure_root_password
99MYSQL_PASSWORD=secure_mysql_password
100INFLUXDB_PASSWORD=secure_influxdb_password
101GRAFANA_PASSWORD=secure_grafana_password
102
103# Home Assistant at http://localhost:8123
104# Zigbee2MQTT at http://localhost:8080
105# Grafana at http://localhost:3000
106EOF
107
108# 3. Start the services
109docker compose up -d
110
111# 4. View logs
112docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/home-assistant-complete/run | bash

Troubleshooting

  • Zigbee2MQTT 'Error: Error while opening serialport' - Check USB device permissions with 'ls -la /dev/ttyUSB*' and ensure correct device path in docker-compose
  • Home Assistant database connection errors - Verify MariaDB container started successfully and MYSQL_PASSWORD matches Home Assistant database configuration
  • MQTT integration showing 'disconnected' - Confirm Mosquitto container is running and accessible on port 1883, check Home Assistant MQTT broker settings
  • InfluxDB setup page shows 'unable to connect' - Wait for container initialization to complete, then access http://localhost:8086 to complete setup wizard
  • Grafana shows 'no data' for Home Assistant metrics - Configure InfluxDB data source in Grafana with correct database credentials and verify Home Assistant InfluxDB integration
  • Zigbee devices fail to pair - Ensure Zigbee2MQTT permit_join is enabled and coordinator firmware supports target device model

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

homeassistantmosquittozigbee2mqttmariadbinfluxdbgrafana

Tags

#homeassistant#smarthome#mqtt#zigbee#automation

Category

Home Lab & Self-Hosting

Related Recipes

Ad Space