Home Assistant has become the gold standard for self-hosted home automation. With support for thousands of integrations, a thriving community, and complete local control, it’s the platform of choice for privacy-conscious smart home enthusiasts. In this comprehensive guide, I’ll walk you through setting up Home Assistant on Docker, the most flexible and portable deployment method available.

💡 This article contains affiliate links. If you buy through them, we earn a small commission at no extra cost to you. Learn more.

Why Choose Home Assistant?

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

Privacy and local control — Unlike cloud-dependent platforms from Google, Amazon, or Apple, Home Assistant runs entirely on your hardware. Your data never leaves your network unless you explicitly configure it to.

Integration ecosystem — With over 2,000 official integrations and countless custom components, Home Assistant connects to virtually every smart home device, service, and protocol imaginable. From Zigbee and Z-Wave to MQTT, HomeKit, and proprietary APIs, HA speaks them all.

Automation power — Home Assistant’s automation engine is extraordinarily flexible. You can create complex routines based on time, device state, location, weather, and virtually any other data point your integrations provide.

Active development — The Home Assistant project releases updates every month, consistently adding new features, integrations, and improvements. The community is massive and helpful.

Cost-effective — Home Assistant is completely free and open source. You only pay for the hardware you run it on.

Why Docker for Home Assistant?

While Home Assistant offers several installation methods (Home Assistant OS, Supervised, Container, and Core), the Docker approach offers unique advantages:

Portability — Docker containers are platform-agnostic. You can run the same configuration on a Raspberry Pi, an old laptop, a dedicated server, or a cloud VM.

Resource efficiency — Unlike the full Home Assistant OS installation, Docker lets you run HA alongside other services on the same host without virtualization overhead.

Flexibility — You maintain full control over your host operating system and can easily integrate HA into existing Docker environments.

Easy backups — Container-based deployments make backup and migration straightforward — just copy your configuration directory and docker-compose file.

Version control — Rolling back to a previous version is as simple as changing a tag in your docker-compose file.

The trade-off? You won’t have access to the Supervisor features or Add-ons available in Home Assistant OS. However, since you’re running Docker anyway, you can simply run those add-on equivalents as separate containers.

Prerequisites

Before we begin, make sure you have:

  • A Linux server or VM (Ubuntu, Debian, or similar)
  • Docker and Docker Compose installed
  • At least 2GB RAM (4GB+ recommended)
  • 32GB+ storage
  • A stable network connection
  • Basic command-line familiarity

For hardware, any modern mini PC with an Intel N100 processor will run Home Assistant beautifully. If you’re using Zigbee or Z-Wave devices, you’ll also want a compatible USB coordinator stick.

Step 1: Create the Directory Structure

First, create a dedicated directory for Home Assistant configuration:

1
2

mkdir -p ~/homeassistant/config
cd ~/homeassistant

This directory will hold all your configuration files, automations, and customizations. Keeping everything in one place makes backups and migrations simple.

Step 2: Create the Docker Compose File

Create a docker-compose.yml file:

1

nano docker-compose.yml

Add the following configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

version: '3.8'

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

Let’s break down these settings:

image — We’re using the official stable release from GitHub Container Registry. You can also specify a specific version tag (e.g., 2026.3.0) for more control.

volumes — The ./config mount persists all your Home Assistant data. The /etc/localtime mount ensures HA uses your host’s timezone.

restart: unless-stopped — This ensures HA automatically starts after server reboots.

privileged: true — Required for certain hardware access and Bluetooth/USB device discovery.

network_mode: host — This gives Home Assistant direct access to your network, which is necessary for mDNS discovery and certain integrations. It means HA will bind directly to your host’s network interfaces.

Step 3: Start Home Assistant

Launch the container:

1

docker-compose up -d

Docker will pull the Home Assistant image (this may take a few minutes) and start the container. You can monitor the logs:

1

docker-compose logs -f homeassistant

Wait for the message “Home Assistant Core started” — initial startup can take 2-5 minutes as HA downloads and installs required dependencies.

Step 4: Initial Configuration

Once Home Assistant is running, open your web browser and navigate to:

http://YOUR_SERVER_IP:8123

You’ll be greeted with the onboarding wizard:

  1. Create your account — This is your primary admin user. Choose a strong password.
  2. Name your home — This helps organize locations and areas.
  3. Set your location — Used for weather, sunrise/sunset, and location-based automations.
  4. Choose your units — Metric or imperial for temperature, distance, etc.
  5. Share analytics — Optional. Helps the Home Assistant team understand usage patterns.

After onboarding, HA will automatically discover devices and services on your network. You’ll likely see integrations for your router, smart TVs, media players, and other networked devices.

Step 5: Configure Essential Integrations

If you plan to use Zigbee, custom sensors, or other MQTT-based devices, set up an MQTT broker. You can run Mosquitto in the same docker-compose file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:latest
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    ports:
      - "1883:1883"
      - "9001:9001"
    restart: unless-stopped

Create the Mosquitto configuration:

1
2

mkdir -p mosquitto/config
nano mosquitto/config/mosquitto.conf

Add:

listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

Restart your stack:

1
2

docker-compose down
docker-compose up -d

In Home Assistant:

  1. Go to Settings → Devices & Services
  2. Click Add Integration
  3. Search for “MQTT”
  4. Enter YOUR_SERVER_IP as the broker and port 1883

Zigbee (If Using Zigbee Devices)

For Zigbee devices, Zigbee2MQTT is the most popular solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt:latest
    volumes:
      - ./zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/ttyUSB0:/dev/ttyACM0
    restart: unless-stopped
    network_mode: host
    privileged: true
    environment:
      - TZ=Europe/Berlin

Replace /dev/ttyUSB0 with your actual Zigbee coordinator device path (check with ls /dev/tty*).

Create the configuration:

1
2

mkdir -p zigbee2mqtt/data
nano zigbee2mqtt/data/configuration.yaml

Add:

1
2
3
4
5
6
7
8
9

homeassistant: true
permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883
serial:
  port: /dev/ttyACM0
frontend:
  port: 8080

After restarting your stack, you can access the Zigbee2MQTT interface at http://YOUR_SERVER_IP:8080.

Node-RED (Optional — Visual Automation)

Node-RED provides a visual programming interface for creating complex automations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

  nodered:
    container_name: nodered
    image: nodered/node-red:latest
    volumes:
      - ./nodered:/data
    ports:
      - "1880:1880"
    restart: unless-stopped
    environment:
      - TZ=Europe/Berlin

Access Node-RED at http://YOUR_SERVER_IP:1880.

Step 6: Basic Automation Example

Let’s create a simple automation. In Home Assistant:

  1. Go to Settings → Automations & Scenes
  2. Click Create Automation
  3. Choose Start with an empty automation

Here’s a simple example that sends a notification at sunset:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

alias: Sunset Notification
description: Send notification when sun sets
trigger:
  - platform: sun
    event: sunset
condition: []
action:
  - service: persistent_notification.create
    data:
      message: "The sun has set. Good evening!"
      title: "Sunset Alert"
mode: single

You can create this in the UI or edit config/automations.yaml directly.

Step 7: Secure Your Installation

Enable SSL/TLS

For external access, use a reverse proxy like Traefik or Caddy with Let’s Encrypt certificates. Never expose Home Assistant directly to the internet without SSL.

Set Up Two-Factor Authentication

Home Assistant supports 2FA:

  1. Go to your user profile (click your name in the bottom left)
  2. Enable Two-factor authentication
  3. Scan the QR code with an authenticator app

Configure Trusted Networks

Edit config/configuration.yaml:

1
2
3
4
5
6
7
8

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

This allows password-free access from your local network while requiring authentication from outside.

Step 8: Backup Strategy

Regular backups are essential. Since we’re using Docker, backing up is straightforward:

Manual Backup

1
2

cd ~/homeassistant
tar -czf ha-backup-$(date +%Y%m%d).tar.gz config/ docker-compose.yml

Automated Backup

Create a cron job:

1

crontab -e

Add:

0 2 * * * cd ~/homeassistant && tar -czf /backup/ha-backup-$(date +\%Y\%m\%d).tar.gz config/ docker-compose.yml

This creates a daily backup at 2 AM.

For more sophisticated backup solutions, consider the Auto Backup integration or using Duplicati in a separate container.

Step 9: Essential Configuration Tips

Customize configuration.yaml

Edit config/configuration.yaml for global settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

homeassistant:
  name: Home
  latitude: !secret latitude
  longitude: !secret longitude
  elevation: 100
  unit_system: metric
  time_zone: Europe/Berlin
  country: DE

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

# Enable the configuration UI
config:

# Enable history
history:

# Enable logbook
logbook:

# Track the sun
sun:

# Enable person tracking
person:

# Enable mobile app support
mobile_app:

# Enable recorder with SQLite
recorder:
  db_url: sqlite:////config/home-assistant_v2.db
  purge_keep_days: 7
  commit_interval: 1

Use Secrets

Store sensitive data in config/secrets.yaml:

1
2
3
4

latitude: 52.5200
longitude: 13.4050
mqtt_user: homeassistant
mqtt_pass: your_secure_password

Reference secrets in configuration files with !secret key_name.

Organize with Packages

For complex configurations, use packages:

1
2
3

# In configuration.yaml
homeassistant:
  packages: !include_dir_named packages/

Create config/packages/ and separate your configuration by domain (lights, climate, sensors, etc.).

Step 10: Performance Optimization

Database Optimization

By default, HA uses SQLite. For better performance with many sensors:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

recorder:
  db_url: sqlite:////config/home-assistant_v2.db
  purge_keep_days: 7
  commit_interval: 1
  exclude:
    domains:
      - automation
      - updater
    entity_globs:
      - sensor.weather_*

For heavy workloads, consider migrating to PostgreSQL or MariaDB.

Resource Limits

If running multiple containers, set resource limits in docker-compose:

1
2
3
4

  homeassistant:
    # ... other settings ...
    mem_limit: 2g
    cpus: 2

Troubleshooting Common Issues

Container Won’t Start

Check logs:

1

docker-compose logs homeassistant

Common causes:

  • Permissions issues on the config directory
  • Port 8123 already in use
  • Corrupted configuration file

Devices Not Discovered

  • Ensure network_mode: host is set
  • Check firewall settings
  • Verify mDNS is working on your network

High CPU Usage

  • Check for polling integrations (switch to push-based when possible)
  • Reduce recorder history retention
  • Disable unused integrations

Integrations Failing

  • Update to the latest Home Assistant version
  • Check integration-specific logs in Settings → System → Logs
  • Verify API keys and credentials

Updating Home Assistant

To update to the latest version:

1
2
3

cd ~/homeassistant
docker-compose pull
docker-compose up -d

Always read the release notes before updating — some updates require configuration changes.

To update to a specific version:

1
2
3

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:2026.3.1

Next Steps

Now that you have Home Assistant running, explore these next steps:

Add integrations — Connect your smart devices, services, and APIs through Settings → Devices & Services.

Create dashboards — Design custom Lovelace dashboards for different rooms, devices, or family members.

Build automations — Start simple (lights on at sunset) and gradually build more complex logic.

Install HACS — The Home Assistant Community Store provides thousands of custom integrations and themes.

Explore voice control — Integrate with Alexa, Google Assistant, or run a local voice assistant with Rhasspy or Wyoming.

Set up presence detection — Use your phone’s app, GPS, or network-based detection to trigger location-based automations.

Join the community — The Home Assistant forums, Discord, and Reddit community are incredibly helpful.

Conclusion

Home Assistant on Docker strikes an excellent balance between flexibility and simplicity. You get the full power of Home Assistant without being locked into a specific operating system or deployment model. The Docker approach integrates seamlessly into existing homelab environments and makes backup, migration, and version control straightforward.

With thousands of integrations, an active community, and monthly feature releases, Home Assistant continues to be the premier choice for self-hosted home automation. Whether you’re starting with a few smart lights or building a comprehensive whole-home automation system, HA scales to meet your needs while keeping your data private and under your control.

The journey from a basic Docker deployment to a fully customized smart home is remarkably rewarding. Start small, experiment often, and enjoy the process of building a home automation system that works exactly the way you want — no cloud dependencies, no monthly fees, no compromises.