Skip to content
SmartBolig logo SmartBolig logo SmartBolig.net

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.

Docker architecture diagram

🤔 Is Docker the Right Choice?

Section titled “🤔 Is Docker the Right Choice?”

✅ Choose Docker if you:

Section titled “✅ 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:

Section titled “❌ Choose Home Assistant OS if you:”
  • Are new to Home Assistant
  • Want everything to “just work”
  • Need Add-ons (Zigbee2MQTT, Node-RED, etc.)

📋 Prerequisites

Section titled “📋 Prerequisites”
  • ✅ Linux server (Ubuntu, Debian, or similar)
  • ✅ Docker installed
  • ✅ Basic terminal knowledge

⚙️ Install Docker

Section titled “⚙️ Install Docker”
Terminal window
# 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

📁 Create Folder Structure

Section titled “📁 Create Folder Structure”
Terminal window
# 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

Section titled “📝 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

🚀 Start Home Assistant

Section titled “🚀 Start Home Assistant”
Terminal window
# 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

🔧 Useful Commands

Section titled “🔧 Useful Commands”
Terminal window
# 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)

Section titled “🔌 USB Devices (Zigbee Stick)”

If you have a Zigbee USB stick or similar:

  1. Find your device:

    Terminal window
    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:

    Terminal window
    docker compose down && docker compose up -d

⚠️ Limitations vs Home Assistant OS

Section titled “⚠️ Limitations vs Home Assistant OS”
FeatureDocker ContainerHome Assistant OS
Add-ons (Z2M, Node-RED)❌ Run separately✅ Integrated
Supervisor❌ No✅ Yes
Auto-backup❌ Manual✅ Yes
UpdatesManual (pull)✅ One click
Flexibility⭐⭐⭐⭐⭐

💾 Backup

Section titled “💾 Backup”

Docker Container has no automatic backup. Do it manually:

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

Section titled “🚀 Next Steps”