Home Assistant Docker Compose Setup: Choose Container with Eyes Open

TL;DR

Home Assistant Container is a standalone container-based installation of Home Assistant Core. This Home Assistant Docker Compose setup is a good fit when you already manage Docker on Linux and want control over updates, backups, networking, and related services.

Use Container only when you already want to own Docker, integrations, backups, updates, and adjacent services; use Home Assistant OS when you want the appliance-like path.

Container does not include Supervisor or add-ons. Home Assistant’s official guidance recommends Home Assistant OS for most users, while Container suits people who deliberately want a Docker-managed installation.

TOC

• Should you use Container or Home Assistant OS?
• Preflight
• Compose file
• Start and verify
• Optional USB and device access
• Secure remote access
• Backups, updates, and rollback
• Failure table
• FAQ

Should you use Container or Home Assistant OS?

Use Container only when you already want to own Docker, integrations, backups, updates, and adjacent services; use Home Assistant OS when you want the appliance-like path.

The official installation-method guidance describes Home Assistant OS as the recommended choice for most users. It provides a more integrated appliance experience, while Container expects you to operate the underlying Linux host and Docker environment.

Choose Home Assistant Container when:

• Docker already runs reliably on your Linux host.
• You want Home Assistant alongside other containers.
• You are comfortable handling filesystem permissions, device access, networking, and upgrades.
• You prefer maintaining your own backup and restore process.

Choose Home Assistant OS when you want Home Assistant to manage more of the platform experience for you. Container is not a cheaper version of Home Assistant OS; it is a different operating model. You trade convenience for control.

The important boundary is simple: Container runs Home Assistant Core in a container. It does not include Supervisor or the add-ons system. If your plan depends on add-ons, choose an installation method that supports them.

Preflight

Before creating the container, confirm that Docker Engine and the Docker Compose plugin work on the Linux host. Choose a durable directory for Home Assistant’s configuration. The example below uses /opt/homeassistant/config; do not place the configuration in a temporary directory or inside a disposable container layer.

Create the directory and ensure your backup system can read it. Also decide whether Home Assistant will share the host with other services. Host networking is convenient, but it means you should understand which host ports are already in use.

If you need Zigbee, Z-Wave, Bluetooth, or another USB-connected integration, identify the device path first. Do not add device mappings “just in case.”

Compose file

Save this as compose.yaml in a project directory:

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

This follows the official Linux installation instructions: the official image, host networking, a persistent /config mount, the host’s local time data mounted read-only, and a restart policy managed by Compose.

There is intentionally no ports: section. With host networking, the container uses the host network namespace, so a port mapping is unnecessary.

Start and verify

From the directory containing compose.yaml, start the service:

docker compose up -d

Check its state:

docker compose ps
docker compose logs --tail=100 homeassistant

Compose provides lifecycle and status commands for starting, stopping, inspecting, and recreating services; its official documentation is the reference for those operations.

When the container is running, open Home Assistant at:

http://HOST_IP:8123

Replace HOST_IP with the Linux host’s address. Complete the initial setup, create your administrator account, and confirm that /opt/homeassistant/config contains Home Assistant files. That directory is the durable state; deleting and recreating the container should not delete it.

If the page does not load, check the container logs first, then verify that another service is not using port 8123 and that the host firewall permits local access.

    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

docker compose pull
docker compose up -d
docker compose logs --tail=100 homeassistant