Automation intermediate ⏱ 60 minutes

Home Assistant: Complete Docker Setup Guide

Full Home Assistant installation with Docker. Integrations, automations, and mobile access.

By homelabbing.io • 2025-12-17
#home-assistant#smart-home#docker#automation#iot

Home Assistant is the leading open-source home automation platform that puts local control and privacy first. Unlike cloud-dependent solutions, Home Assistant runs entirely on your hardware, giving you complete control over your smart home while supporting thousands of devices and services.

In this comprehensive guide, you’ll learn how to deploy Home Assistant using Docker, integrate various smart devices, create powerful automations, and build a robust home automation system that respects your privacy.

Why Home Assistant?

Home Assistant stands out in the crowded smart home landscape for several compelling reasons:

Privacy and Local Control: All data stays on your network. No cloud dependency means your home continues working even when the internet is down.

Unified Interface: Control devices from different manufacturers through a single, beautiful interface. No more juggling multiple apps.

Powerful Automations: Create complex automations based on time, device states, location, and virtually any other trigger you can imagine.

Extensibility: With over 2,000 integrations and a thriving community, you can connect almost anything to Home Assistant.

No Subscription Fees: Home Assistant is completely free and open-source. Optional Home Assistant Cloud service is available but not required.

Prerequisites

Before starting, ensure you have:

  • A Linux server or VM with Docker and Docker Compose installed
  • At least 2GB RAM and 32GB storage (SSD recommended)
  • Network access to your smart home devices
  • Basic familiarity with YAML configuration
  • Optional: Zigbee or Z-Wave USB coordinator for wireless devices

Docker Compose Setup

We’ll deploy Home Assistant using Docker Compose for easy management and integration with other services. This setup provides persistence, automatic restarts, and network access.

Create your Home Assistant directory structure:

mkdir -p /opt/homeassistant/{config,backups}
cd /opt/homeassistant

Create a docker-compose.yml file:

version: '3.8'

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    network_mode: host
    privileged: true
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    environment:
      - TZ=America/New_York
    devices:
      # Uncomment if using USB Zigbee/Z-Wave coordinator
      # - /dev/ttyUSB0:/dev/ttyUSB0
      # - /dev/ttyACM0:/dev/ttyACM0

  # Optional: MQTT Broker for device communication
  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:latest
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    environment:
      - TZ=America/New_York

networks:
  default:
    name: homeassistant

Create the MQTT broker configuration:

mkdir -p mosquitto/config
cat > mosquitto/config/mosquitto.conf << EOF
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

listener 1883
allow_anonymous false
password_file /mosquitto/config/password.txt

listener 9001
protocol websockets
EOF

Set up MQTT authentication:

# Create MQTT user (run this from host)
docker run -it --rm -v $(pwd)/mosquitto/config:/mosquitto/config eclipse-mosquitto mosquitto_passwd -c /mosquitto/config/password.txt mqtt-user

Start the services:

docker-compose up -d

Home Assistant will be available at http://YOUR-SERVER-IP:8123 after about 60 seconds of initialization.

Initial Configuration

When you first access Home Assistant, you’ll go through the onboarding process:

  1. Create Admin Account: Choose a strong username and password
  2. Name Your Home: Set your home’s name and location for weather and sun automation
  3. Share Analytics: Optionally help improve Home Assistant by sharing anonymous usage data
  4. Install Integrations: Home Assistant will auto-discover devices on your network

After onboarding, you’ll reach the main dashboard. Let’s configure essential settings.

Configuration.yaml Overview

Home Assistant uses YAML files for configuration. The main file is /config/configuration.yaml. While most integrations can now be configured through the UI, understanding YAML configuration is valuable for advanced features.

Basic configuration structure:

# Core configuration
homeassistant:
  name: Home
  latitude: 40.7128
  longitude: -74.0060
  elevation: 10
  unit_system: metric
  time_zone: America/New_York
  currency: USD
  country: US

  # Customize entities
  customize:
    sensor.bedroom_temperature:
      friendly_name: "Bedroom Temp"
      icon: mdi:thermometer

# Enable the default frontend
frontend:
  themes: !include_dir_merge_named themes

# Enable configuration through UI
config:

# Uncomment to enable logger for debugging
# logger:
#   default: info
#   logs:
#     homeassistant.components.mqtt: debug

# Enable Home Assistant iOS/Android app
mobile_app:

# Enable person tracking
person:

# Enable zone definition
zone:
  - name: Work
    latitude: 40.7589
    longitude: -73.9851
    radius: 100
    icon: mdi:briefcase

# Enable automation UI
automation: !include automations.yaml

# Enable scene UI
scene: !include scenes.yaml

# Enable script UI
script: !include scripts.yaml

# Text-to-speech
tts:
  - platform: google_translate
    service_name: google_say

# Enable system health
system_health:

# Enable history
history:
  include:
    domains:
      - sensor
      - switch
      - light
      - climate
      - binary_sensor

# Enable recorder (database)
recorder:
  purge_keep_days: 7
  commit_interval: 30
  db_url: sqlite:////config/home-assistant_v2.db
  exclude:
    domains:
      - automation
      - updater
    entity_globs:
      - sensor.weather_*

# Energy monitoring
energy:

# MQTT Integration
mqtt:
  broker: localhost
  port: 1883
  username: mqtt-user
  password: YOUR_MQTT_PASSWORD
  discovery: true
  birth_message:
    topic: 'homeassistant/status'
    payload: 'online'
  will_message:
    topic: 'homeassistant/status'
    payload: 'offline'

After editing configuration files, always validate your configuration before restarting:

Settings > System > Check Configuration

Adding Integrations

Home Assistant supports thousands of integrations. Here are essential ones to get started:

MQTT Integration

MQTT is crucial for many DIY devices and commercial smart home products.

  1. Navigate to Settings > Devices & Services
  2. Click Add Integration
  3. Search for “MQTT”
  4. Configure:
    • Broker: localhost (or mosquitto if using container name)
    • Port: 1883
    • Username: mqtt-user
    • Password: your password

Enable MQTT discovery to automatically detect devices:

mqtt:
  discovery: true
  discovery_prefix: homeassistant

Network Device Discovery

Home Assistant automatically discovers many devices using mDNS, SSDP, and other protocols:

  • Philips Hue bridges
  • Sonos speakers
  • Google Cast devices
  • Smart TVs
  • Network printers
  • And many more

Check Settings > Devices & Services > Discovered to see what’s been found.

Manual Integration Examples

Tasmota Devices:

# Tasmota devices auto-discover via MQTT
# Ensure SetOption19 1 is set on Tasmota device

ESPHome:

  1. Add ESPHome integration
  2. Enter device hostname or IP
  3. Enter encryption key from device config

Weather Integration:

  1. Add OpenWeatherMap integration
  2. Register for free API key at openweathermap.org
  3. Enter API key and location

Speed Test:

speedtestdotnet:
  scan_interval:
    hours: 1
  monitored_conditions:
    - ping
    - download
    - upload

Creating Automations

Automations are the heart of Home Assistant. They follow a trigger-condition-action pattern.

Basic Automation Structure

automation:
  - alias: "Morning Routine"
    description: "Turn on lights at sunrise"
    trigger:
      - platform: sun
        event: sunrise
        offset: "-00:30:00"
    condition:
      - condition: state
        entity_id: person.john
        state: 'home'
    action:
      - service: light.turn_on
        target:
          entity_id: light.bedroom
        data:
          brightness_pct: 20
          kelvin: 2700

Practical Automation Examples

Motion-Activated Lights:

automation:
  - alias: "Hallway Motion Light"
    trigger:
      - platform: state
        entity_id: binary_sensor.hallway_motion
        to: 'on'
    condition:
      - condition: numeric_state
        entity_id: sensor.hallway_illuminance
        below: 50
      - condition: time
        after: '18:00:00'
        before: '23:00:00'
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway
        data:
          brightness_pct: 50
      - wait_for_trigger:
          - platform: state
            entity_id: binary_sensor.hallway_motion
            to: 'off'
            for:
              minutes: 5
      - service: light.turn_off
        target:
          entity_id: light.hallway

Climate Control:

automation:
  - alias: "Smart Thermostat - Away Mode"
    trigger:
      - platform: state
        entity_id: person.john
        to: 'not_home'
        for:
          minutes: 30
    action:
      - service: climate.set_temperature
        target:
          entity_id: climate.living_room
        data:
          temperature: 18

  - alias: "Smart Thermostat - Home Mode"
    trigger:
      - platform: state
        entity_id: person.john
        to: 'home'
    action:
      - service: climate.set_temperature
        target:
          entity_id: climate.living_room
        data:
          temperature: 21

Notification on Water Leak:

automation:
  - alias: "Water Leak Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.basement_water_leak
        to: 'on'
    action:
      - service: notify.mobile_app_johns_phone
        data:
          title: "Water Leak Detected!"
          message: "Water detected in basement"
          data:
            priority: high
            tag: water_leak
      - service: switch.turn_off
        target:
          entity_id: switch.water_main_valve

Energy Saving:

automation:
  - alias: "Turn Off Everything at Bedtime"
    trigger:
      - platform: time
        at: "23:00:00"
    action:
      - service: light.turn_off
        target:
          area_id:
            - living_room
            - kitchen
            - dining_room
      - service: media_player.turn_off
        target:
          entity_id: all
      - service: climate.set_preset_mode
        target:
          entity_id: climate.living_room
        data:
          preset_mode: sleep

Dashboard Customization

Home Assistant’s Lovelace UI is highly customizable. You can create multiple dashboards for different purposes.

Creating a Custom Dashboard

  1. Go to Overview
  2. Click three dots menu > Edit Dashboard
  3. Add cards using the visual editor

Example dashboard YAML configuration:

views:
  - title: Home
    icon: mdi:home
    cards:
      - type: weather-forecast
        entity: weather.home

      - type: entities
        title: Climate
        entities:
          - entity: sensor.living_room_temperature
            name: Living Room
          - entity: sensor.bedroom_temperature
            name: Bedroom
          - entity: climate.thermostat

      - type: horizontal-stack
        cards:
          - type: button
            entity: light.living_room
            tap_action:
              action: toggle
            icon: mdi:ceiling-light
          - type: button
            entity: switch.tv_power
            tap_action:
              action: toggle
            icon: mdi:television

      - type: gauge
        entity: sensor.speedtest_download
        name: Download Speed
        unit: Mbps
        min: 0
        max: 100
        severity:
          green: 50
          yellow: 25
          red: 0

  - title: Automations
    icon: mdi:robot
    cards:
      - type: entities
        title: Active Automations
        entities:
          - automation.morning_routine
          - automation.evening_lights
          - automation.security_armed
        show_header_toggle: true

Mobile App Access

The Home Assistant mobile app provides full access to your smart home from anywhere.

Setting Up Remote Access

Option 1: Home Assistant Cloud (Nabu Casa)

  • Monthly subscription supports development
  • Automatic secure remote access
  • No port forwarding required
  • Includes Alexa/Google Assistant integration

Option 2: Self-Hosted VPN

  • Use WireGuard or OpenVPN
  • Free but requires setup
  • Access your entire home network

Option 3: Reverse Proxy with SSL

Using Nginx Proxy Manager:

# Add to docker-compose.yml
  nginx-proxy-manager:
    image: jc21/nginx-proxy-manager:latest
    restart: unless-stopped
    ports:
      - '80:80'
      - '443:443'
      - '81:81'
    volumes:
      - ./nginx/data:/data
      - ./nginx/letsencrypt:/etc/letsencrypt

Configure proxy host:

  • Domain: homeassistant.yourdomain.com
  • Forward to: YOUR-SERVER-IP:8123
  • Enable SSL with Let’s Encrypt

Mobile App Setup

  1. Download Home Assistant app from App Store or Google Play
  2. Open app on same network as Home Assistant
  3. App will auto-discover your instance
  4. Login with your credentials
  5. Enable location tracking for presence detection

Configure notifications:

# Add to configuration.yaml
notify:
  - name: mobile_app_johns_phone
    platform: group
    services:
      - service: mobile_app_iphone

Hardware Recommendations

Zigbee Coordinators

For Zigbee devices, you need a coordinator. Top recommendations:

Sonoff Zigbee 3.0 USB Dongle Plus - Budget-friendly, wide compatibility, CC2652P chip, excellent range with external antenna. Around 25 USD.

ConBee II - Reliable, well-supported, works with Zigbee and some 6LoWPAN devices. Around 40 USD.

SLZB-06 - Network-based coordinator, no USB required, can be placed anywhere on your network for optimal coverage. Around 35 USD.

Z-Wave Controllers

Zooz ZST10 700 Series USB Stick - Latest Z-Wave standard, backwards compatible, good range. Around 30 USD.

Aeotec Z-Stick 7 - Reliable, well-supported, battery backup for portable network healing. Around 50 USD.

Server Hardware

Minimum Setup:

  • Raspberry Pi 4 with 4GB RAM
  • 32GB microSD card
  • Good for 50-100 devices

Recommended Setup:

  • Intel NUC or similar mini PC
  • 8GB RAM
  • 256GB SSD
  • Can handle 500+ devices plus additional containers

Production Setup:

  • Server with 16GB+ RAM
  • SSD storage
  • Redundant power supply
  • Perfect for large deployments and advanced features

Security Considerations

Securing your Home Assistant instance is critical since it controls physical devices in your home.

Essential Security Practices

1. Strong Authentication:

homeassistant:
  auth_providers:
    - type: homeassistant
    - type: trusted_networks
      trusted_networks:
        - 192.168.1.0/24
      allow_bypass_login: true

2. Enable 2FA:

  • Go to Profile > Security
  • Enable Multi-Factor Authentication
  • Use authenticator app like Authy or Google Authenticator

3. Regular Backups:

Create automated backup automation:

automation:
  - alias: "Daily Backup"
    trigger:
      - platform: time
        at: "03:00:00"
    action:
      - service: backup.create
        data:
          name: "Automated Backup {{ now().strftime('%Y-%m-%d') }}"

4. Network Segmentation:

  • Put IoT devices on separate VLAN
  • Restrict internet access for Chinese cloud cameras
  • Use firewall rules to control communication

5. Update Regularly:

# Enable update notifications
automation:
  - alias: "Update Available Notification"
    trigger:
      - platform: state
        entity_id: binary_sensor.updater
        to: 'on'
    action:
      - service: notify.mobile_app
        data:
          message: "Home Assistant update available"

6. Secure Secrets:

Store sensitive data in secrets.yaml:

# secrets.yaml
mqtt_password: your_secure_password
api_key: your_api_key

# configuration.yaml
mqtt:
  password: !secret mqtt_password

7. Restrict API Access:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.18.0.0/16
  ip_ban_enabled: true
  login_attempts_threshold: 5

Advanced Features

Template Sensors

Create virtual sensors based on other entities:

template:
  - sensor:
      - name: "Average Indoor Temperature"
        unit_of_measurement: "°C"
        state: >
          {% set temps = [
            states('sensor.living_room_temperature') | float,
            states('sensor.bedroom_temperature') | float,
            states('sensor.kitchen_temperature') | float
          ] %}
          {{ (temps | sum / temps | length) | round(1) }}

      - name: "Power Usage Cost Today"
        unit_of_measurement: "USD"
        state: >
          {{ (states('sensor.energy_today') | float * 0.12) | round(2) }}

Input Helpers

Create input helpers for manual control and automation logic:

input_boolean:
  guest_mode:
    name: Guest Mode
    icon: mdi:account-multiple

input_number:
  thermostat_setpoint:
    name: Temperature Setpoint
    min: 15
    max: 25
    step: 0.5
    unit_of_measurement: °C

input_select:
  house_mode:
    name: House Mode
    options:
      - Home
      - Away
      - Night
      - Vacation
    icon: mdi:home-account

Custom Scripts

Create reusable scripts:

script:
  movie_time:
    alias: "Movie Time"
    sequence:
      - service: light.turn_off
        target:
          area_id: living_room
      - service: media_player.turn_on
        target:
          entity_id: media_player.tv
      - service: light.turn_on
        target:
          entity_id: light.led_strip
        data:
          brightness_pct: 20
          rgb_color: [128, 0, 128]

Troubleshooting

Common Issues

Home Assistant won’t start:

  • Check logs: docker logs homeassistant
  • Validate configuration: Settings > Check Configuration
  • Check YAML syntax with online validator

Devices not discovered:

  • Ensure mDNS/multicast is enabled on network
  • Check that devices are on same VLAN
  • Disable AP isolation on WiFi

Automations not triggering:

  • Check automation traces: Settings > Automations > Select automation > Traces
  • Verify trigger conditions are met
  • Enable debug logging for specific components

Database growing too large:

recorder:
  purge_keep_days: 3
  purge_interval: 1
  exclude:
    domains:
      - automation
      - script

High CPU/Memory usage:

  • Reduce recorder retention
  • Disable unused integrations
  • Increase scan interval for sensors
  • Consider upgrading hardware

Conclusion

You now have a fully functional Home Assistant instance running in Docker, ready to control and automate your smart home. Home Assistant’s true power comes from its flexibility and the endless possibilities for customization.

Start small with basic automations and gradually expand as you learn more about the platform. Join the active Home Assistant community on forums, Reddit, and Discord for inspiration and support.

Key takeaways:

  • Home Assistant provides local, privacy-focused home automation
  • Docker deployment offers easy management and portability
  • MQTT enables integration with countless DIY and commercial devices
  • Automations can be as simple or complex as you need
  • Regular backups and security practices are essential
  • The community is incredibly helpful for learning and troubleshooting

Your smart home journey has just begun. Happy automating!

Additional Resources