# Home Assistant Smart Home Hub

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

- Category: Home Lab & Self-Hosting
- Difficulty: intermediate
- Components: homeassistant, mosquitto, zigbee2mqtt, mariadb, influxdb, grafana
- Tags: homeassistant, smarthome, mqtt, zigbee, automation
- Source: https://docker.recipes/homelab/home-assistant-complete

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

## 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

## Use cases

- Complete smart home automation with lights, thermostats, security cameras, and door locks
- DIY IoT sensor networks using ESP32/Arduino devices with MQTT communication
- Home energy monitoring with solar panel production and consumption analytics
- Multi-protocol device integration combining Zigbee, Z-Wave, WiFi, and Bluetooth devices
- Privacy-focused smart home avoiding cloud-dependent solutions like SmartThings or Wink
- Home lab enthusiasts building comprehensive IoT data collection and visualization systems
- Rental 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    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:
    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:
    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:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - ha_net

volumes:
  ha_config:
  mosquitto_config:
  mosquitto_data:
  mosquitto_log:
  zigbee_data:
  mariadb_data:
  influxdb_data:
  grafana_data:

networks:
  ha_net:
```

## .env

```bash
# Home Assistant
MYSQL_ROOT_PASSWORD=secure_root_password
MYSQL_PASSWORD=secure_mysql_password
INFLUXDB_PASSWORD=secure_influxdb_password
GRAFANA_PASSWORD=secure_grafana_password

# Home Assistant at http://localhost:8123
# Zigbee2MQTT at http://localhost:8080
# Grafana at http://localhost:3000
```

## Usage notes

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

## 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

