Running Home Assistant in Docker gives you flexibility and control over your smart home hub. Unlike Home Assistant OS on a Raspberry Pi (which requires dedicated hardware), Docker lets you run Home Assistant alongside other services on any Linux machine, making it ideal for users who want to consolidate their home server infrastructure. This guide covers installation, configuration, and essential maintenance.

TL;DR

Install Docker, create a configuration directory, then run the Home Assistant container with proper volume mounts. Access the web interface at http://localhost:8123 and complete the onboarding wizard. Use Docker Compose for easier management, and set up automated backups for your configuration directory.

Prerequisites

Before installing Home Assistant in Docker, ensure you have:

  • Docker installed on your system. Docker Engine 20.10 or later is recommended. Install from Docker’s official documentation.
  • Docker Compose (optional but recommended). Version 2.0 or later for easier container management.
  • Linux system with sufficient resources. Home Assistant needs at least 2 GB RAM and 32 GB storage, though 4 GB RAM and 64 GB storage are recommended for better performance.
  • Network access for your devices. Home Assistant needs to communicate with smart devices on your local network.

Installation Methods

There are two main ways to run Home Assistant in Docker: using Docker directly or using Docker Compose. Docker Compose is recommended as it simplifies configuration and makes updates easier.

Method 1: Docker Run (Quick Start)

For a quick installation, you can use Docker’s docker run command directly:

Terminal window
# Create configuration directory
mkdir -p ~/homeassistant/config


# Run Home Assistant container
docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=America/New_York \
  -v ~/homeassistant/config:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Replace America/New_York with your timezone and adjust the volume path as needed. The –network=host flag allows Home Assistant to discover devices on your local network.

Docker Compose provides better organization and easier updates. Create a docker-compose.yml file:

version: '3'
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
    environment:
      - TZ=America/New_York

Save this file as docker-compose.yml in a directory (e.g., ~/homeassistant), then start the container:

Terminal window
# Navigate to your Home Assistant directory
cd ~/homeassistant


# Start the container
docker compose up -d

The -d flag runs the container in detached mode (in the background). You can view logs with docker compose logs -f.

Initial Setup

After starting the container, wait a few minutes for Home Assistant to initialize. Then access the web interface:

  • Local access: Open http://localhost:8123 in your browser
  • Network access: Use http://<your-server-ip>:8123 from other devices on your network

The first time you access Home Assistant, you’ll see the onboarding wizard. Complete these steps:

  • Create an account: Set up your administrator username and password
  • Set location: Enter your home address or coordinates for location-based features
  • Configure timezone: Ensure your timezone matches the TZ environment variable
  • Choose units: Select metric or imperial for measurements

Configuration Directory Structure

Your Home Assistant configuration is stored in the mounted volume. The typical structure looks like this:

config/
├── configuration.yaml      # Main configuration file
├── automations.yaml       # Automation definitions
├── scripts.yaml          # Script definitions
├── scenes.yaml           # Scene definitions
├── groups.yaml           # Group definitions
├── secrets.yaml          # Sensitive data (API keys, passwords)
├── .storage/             # Internal database and cache
├── tts/                  # Text-to-speech cache
└── www/                  # Custom web assets

The .storage directory contains Home Assistant’s internal database, entity registry, and other runtime data. Always include this in your backups.

Basic Maintenance

Updating Home Assistant

Home Assistant releases updates regularly. To update your Docker installation:

Terminal window
# Stop the container
docker compose down


# Pull the latest image
docker compose pull


# Start with the new image
docker compose up -d

Alternatively, if using docker run:

Terminal window
# Stop and remove the old container
docker stop homeassistant
docker rm homeassistant


# Pull the latest image
docker pull ghcr.io/home-assistant/home-assistant:stable


# Run with the same command as before
docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=America/New_York \
  -v ~/homeassistant/config:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Backing Up Your Configuration

Regular backups are essential. The simplest approach is to back up your entire configuration directory:

Terminal window
# Create a backup with timestamp
tar -czf homeassistant-backup-$(date +%Y%m%d).tar.gz \
  ~/homeassistant/config


# Or using Docker Compose directory
cd ~/homeassistant
tar -czf ../homeassistant-backup-$(date +%Y%m%d).tar.gz config/

For automated backups, create a cron job or systemd timer:

Terminal window
# Add to crontab (crontab -e)
# Backup Home Assistant daily at 2 AM
0 2 * * * tar -czf /backups/homeassistant-$(date +\%Y\%m\%d).tar.gz ~/homeassistant/config

Viewing Logs

Monitor Home Assistant logs to troubleshoot issues:

Terminal window
# View logs (Docker Compose)
docker compose logs -f homeassistant


# View logs (docker run)
docker logs -f homeassistant


# View last 100 lines
docker logs --tail 100 homeassistant

Restarting the Container

Restart Home Assistant when making configuration changes or troubleshooting:

Terminal window
# Restart (Docker Compose)
docker compose restart homeassistant


# Restart (docker run)
docker restart homeassistant

Common Issues and Solutions

Container Won’t Start

If the container fails to start:

  • Check logs: docker logs homeassistant
  • Verify the configuration directory has proper permissions
  • Ensure port 8123 isn’t already in use: netstat -tulpn | grep 8123
  • Check disk space: df -h

Can’t Access Web Interface

If you can’t reach the web interface:

  • Wait 5-10 minutes after first start for initialization
  • Verify the container is running: docker ps | grep homeassistant
  • Check firewall rules if accessing from another device
  • Try accessing via IP address instead of localhost

Device Discovery Not Working

If Home Assistant can’t discover devices on your network:

  • Ensure –network=host or network_mode: host is set
  • Check that your Docker host can reach devices on the local network
  • Some integrations require additional network configuration or host networking

Advanced Configuration

Resource Limits

You can limit container resources to prevent it from consuming too much CPU or memory:

services:
  homeassistant:
    # ... other configuration
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Health Checks

Add a health check to monitor container status:

services:
  homeassistant:
    # ... other configuration
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8123"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Why Docker Over Home Assistant OS?

Running Home Assistant in Docker offers several advantages:

  • Flexibility: Run alongside other services on the same machine
  • Resource efficiency: Share system resources with other containers
  • Easy backups: Simply back up the configuration directory
  • Version control: Easier to test different Home Assistant versions
  • Infrastructure consolidation: Use existing server infrastructure

However, Home Assistant OS provides a more integrated experience with built-in add-ons and automatic updates. Choose Docker if you want more control or need to run other services on the same hardware.

Next Steps

With Home Assistant running in Docker, you can:

  • Add integrations for your smart devices
  • Create automations to control devices based on conditions
  • Set up the mobile app for remote access
  • Explore add-ons (though some may require Home Assistant OS)
  • Configure backups and monitoring for your Docker setup

For hardware-specific setup, see our guide on Setting Up a Raspberry Pi for Home Assistant if you’re running Docker on a Pi.