# Home Assistant Full Stack

> Complete smart home platform with Home Assistant, Mosquitto MQTT, Zigbee2MQTT, and InfluxDB.

- Category: Home Lab & Self-Hosting
- Difficulty: advanced
- Components: home-assistant, mosquitto, zigbee2mqtt, influxdb, grafana
- Tags: home-assistant, smart-home, mqtt, zigbee, iot
- Source: https://docker.recipes/homelab/home-assistant-full-stack

## Overview

Home Assistant is an open-source home automation platform that puts local control and privacy first, integrating with over 2000 devices and services to create comprehensive smart home solutions. Unlike cloud-dependent alternatives, Home Assistant runs entirely on your local hardware, ensuring your smart home data remains private while providing powerful automation capabilities through its sophisticated rule engine and intuitive dashboard interface. This full-stack deployment combines Home Assistant with essential smart home infrastructure components: Eclipse Mosquitto MQTT broker for device communication, Zigbee2MQTT for direct Zigbee device control without proprietary hubs, InfluxDB for time-series data storage of sensor readings and device states, and Grafana for creating detailed analytics dashboards of your home's operational data. The stack creates a complete smart home ecosystem where MQTT serves as the communication backbone, Zigbee2MQTT eliminates vendor lock-in by directly controlling Zigbee devices, InfluxDB captures historical data for trend analysis, and Grafana transforms raw sensor data into meaningful visualizations. This combination is ideal for privacy-conscious smart home enthusiasts, IoT developers building custom solutions, homelab operators wanting comprehensive home monitoring, and anyone seeking to create advanced automation rules based on historical data patterns and real-time analytics.

## Features

- Over 2000 device integrations including Philips Hue, Nest, Ring, Tesla, and major IoT platforms
- Local Zigbee device control through Zigbee2MQTT without requiring proprietary hubs or cloud services
- High-performance time-series data storage with InfluxDB's purpose-built architecture for IoT sensor data
- Advanced automation engine with triggers, conditions, and actions for complex smart home scenarios
- Rich visualization dashboards in Grafana with 50+ chart types for home energy monitoring and sensor analytics
- MQTT broker infrastructure supporting thousands of concurrent device connections with QoS guarantees
- Flux query language in InfluxDB for complex time-based analytics and data retention policies
- Voice assistant integration with Google Assistant, Alexa, and local speech processing

## Use cases

- Complete smart home automation with lighting, climate, security, and entertainment system integration
- Home energy monitoring with solar panel output tracking, usage analytics, and cost optimization
- Indoor air quality management using multiple sensor types with historical trending and alerting
- Security system integration combining cameras, door sensors, and motion detectors with intelligent notifications
- Greenhouse or hydroponic system monitoring with temperature, humidity, and soil moisture automation
- Multi-zone HVAC optimization using occupancy sensors and weather data for energy efficiency
- Home lab infrastructure monitoring combining network equipment stats with environmental conditions

## Prerequisites

- Minimum 4GB RAM recommended (2GB+ for Home Assistant, 1GB+ for InfluxDB, 512MB+ for Grafana)
- USB Zigbee coordinator device (CC2531, CC2652, or Sonoff Zigbee dongle) connected to /dev/ttyUSB0
- Port availability: 8123 (Home Assistant), 3000 (Grafana), 8086 (InfluxDB), 1883/9001 (MQTT)
- Basic understanding of YAML configuration for Home Assistant automations and device setup
- Network access to smart home devices and understanding of local IP addressing
- Familiarity with MQTT topics and JSON payloads for custom device integration

## docker-compose.yml

```yaml
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    environment:
      TZ: ${TZ}
    volumes:
      - ha_config:/config
    ports:
      - "8123:8123"
    privileged: true
    depends_on:
      - mosquitto
      - influxdb
    networks:
      - homelab-net
    restart: unless-stopped

  mosquitto:
    image: eclipse-mosquitto:latest
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - mosquitto_config:/mosquitto/config
      - mosquitto_data:/mosquitto/data
      - mosquitto_log:/mosquitto/log
    networks:
      - homelab-net
    restart: unless-stopped

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:latest
    environment:
      TZ: ${TZ}
    volumes:
      - zigbee2mqtt_data:/app/data
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    depends_on:
      - mosquitto
    ports:
      - "8080:8080"
    networks:
      - homelab-net
    restart: unless-stopped

  influxdb:
    image: influxdb:2.7
    environment:
      DOCKER_INFLUXDB_INIT_MODE: setup
      DOCKER_INFLUXDB_INIT_USERNAME: ${INFLUX_USER}
      DOCKER_INFLUXDB_INIT_PASSWORD: ${INFLUX_PASSWORD}
      DOCKER_INFLUXDB_INIT_ORG: ${INFLUX_ORG}
      DOCKER_INFLUXDB_INIT_BUCKET: ${INFLUX_BUCKET}
    ports:
      - "8086:8086"
    volumes:
      - influxdb_data:/var/lib/influxdb2
    networks:
      - homelab-net
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - influxdb
    networks:
      - homelab-net
    restart: unless-stopped

volumes:
  ha_config:
  mosquitto_config:
  mosquitto_data:
  mosquitto_log:
  zigbee2mqtt_data:
  influxdb_data:
  grafana_data:

networks:
  homelab-net:
    driver: bridge
```

## .env

```bash
# Timezone
TZ=UTC

# InfluxDB
INFLUX_USER=admin
INFLUX_PASSWORD=secure_influx_password
INFLUX_ORG=homelab
INFLUX_BUCKET=homeassistant

# Grafana
GRAFANA_PASSWORD=secure_grafana_password
```

## Usage notes

- Home Assistant at http://localhost:8123
- Zigbee2MQTT UI at http://localhost:8080
- Grafana dashboards at http://localhost:3000
- Configure Zigbee coordinator path in Zigbee2MQTT

## Troubleshooting

- Zigbee2MQTT 'Error: Could not open path': Check USB device permissions with 'sudo chown root:dialout /dev/ttyUSB0' and verify coordinator device path
- Home Assistant 'Recorder could not start': Ensure InfluxDB is fully initialized and accessible on port 8086 before Home Assistant starts
- Grafana shows 'Bad Gateway' for InfluxDB: Verify InfluxDB authentication token and organization name match environment variables in both services
- MQTT devices not connecting: Check Mosquitto broker allows anonymous connections or configure authentication in mosquitto.conf
- High memory usage: Enable InfluxDB data retention policies to automatically delete old sensor data and reduce storage requirements
- Zigbee devices not pairing: Enable Zigbee2MQTT permit_join mode through the web UI at port 8080 before attempting device pairing

