Home Assistant in Docker

Medium 20 min Free

Docker is the flexible way to run Home Assistant. Perfect if you already have a server or NAS running.

🤔 Is Docker the Right Choice?

✅ Choose Docker if you:

• Have an existing server/NAS
• Want to run other services (Plex, Nextcloud, etc.)
• Prefer manual control
• Already know Docker

❌ Choose Home Assistant OS if you:

• Are new to Home Assistant
• Want everything to “just work”
• Need Add-ons (Zigbee2MQTT, Node-RED, etc.)

Tip

New to Home Assistant? Start with Raspberry Pi installation - it’s much easier.

📋 Prerequisites

• ✅ Linux server (Ubuntu, Debian, or similar)
• ✅ Docker installed
• ✅ Basic terminal knowledge

⚙️ Install Docker

Ubuntu/Debian

# Update package list
sudo apt update && sudo apt upgrade -y

# Install Docker with official script
curl -fsSL https://get.docker.com | sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and in again (or run):
newgrp docker

# Verify installation
docker --version
docker compose version

Synology NAS

1. Open Package Center
2. Search for “Container Manager” (formerly Docker)
3. Click Install
4. Continue with Docker Compose method below

📁 Create Folder Structure

# Create folders
mkdir -p ~/docker/homeassistant/config
cd ~/docker/homeassistant

Your structure:

~/docker/
└── homeassistant/
    ├── config/          ← All HA files stored here
    └── docker-compose.yml

📝 Docker Compose File

Create the file docker-compose.yml:

docker-compose.yml

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      - TZ=Europe/London

Why network_mode: host?

Home Assistant scans your network for devices (mDNS, SSDP). With host networking, auto-discovery works. Without it, HA won’t find your devices automatically.

🚀 Start Home Assistant

# Start in background
docker compose up -d

# Follow logs (Ctrl+C to stop)
docker compose logs -f homeassistant

Then open: http://YOUR-SERVER-IP:8123

Tip

First startup takes 2-5 minutes. You’ll see “Preparing Home Assistant” until it’s ready.

🔧 Useful Commands

# See status
docker compose ps

# See logs
docker compose logs -f homeassistant

# Restart
docker compose restart homeassistant

# Stop
docker compose down

# Update to latest version
docker compose pull
docker compose up -d

# See resource usage
docker stats homeassistant

🔌 USB Devices (Zigbee Stick)

If you have a Zigbee USB stick or similar:

1. Find your device:

   ls -la /dev/serial/by-id/

2. Add to docker-compose.yml:

   docker-compose.yml

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

3. Restart container:

   docker compose down && docker compose up -d

⚠️ Limitations vs Home Assistant OS

Feature	Docker Container	Home Assistant OS
Add-ons (Z2M, Node-RED)	❌ Run separately	✅ Integrated
Supervisor	❌ No	✅ Yes
Auto-backup	❌ Manual	✅ Yes
Updates	Manual (pull)	✅ One click
Flexibility	⭐⭐⭐	⭐⭐

💾 Backup

Docker Container has no automatic backup. Do it manually:

# Stop HA first (optional, but safer)
docker compose stop homeassistant

# Backup config folder
tar -czvf homeassistant-backup-$(date +%Y%m%d).tar.gz config/

# Start HA again
docker compose start homeassistant

🚀 Next Steps

📡 Zigbee2MQTT

Run Zigbee2MQTT as Docker container alongside HA.

Set up Zigbee2MQTT →

⚡ First automation

Create your first automation in Home Assistant.

Create automations →