HomeAssistant with Docker Swarm

Raspberry Pi 5

I’ve been tinkering with a Raspberry Pi 5 recently as thought of sharing the docker-compose file that worked for me. There are examples of docker compose files but rarely for a Docker Swarm setup, which is my preferred orchestration layer for containers as it is simple yet robust enough for most workloads.

You should be able to update your containers without any downtime even though it is a singular node swarm cluster.

There are additional steps that you can take to secure the infrastructure by having the instance run in the docker network (and potentially use avahi reflector to propagate mDNS into the docker network) but that seems to be a bit overkill for a mini home project. 😅

2025-07-01 Update

Turns out there are good reasons to use docker compose instead of docker swarm as there are some specifications that do not work in docker swarm. E.g. devices to expose USB devices to the container. See below for the updated docker compose file.

Updated docker composefile

services:
  app:
    image: "ghcr.io/home-assistant/home-assistant:stable"
    environment:
      - TZ=<YOUR_TIMEZONE>
    volumes:
      - <PATH_TO_CONFIG>:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
      - /dev/serial/by-id:/dev/serial/by-id
    # Pretty crucial for a home automation setup, e.g. adding signal adapters directly to the Raspberry Pi
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: always
    network_mode: host

Old docker swarm yaml

version: "3.8"

services:
  app:
    image: "ghcr.io/home-assistant/home-assistant:stable"
    environment:
      - TZ=<YOUR_TIMEZONE>
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    deploy:
      replicas: 1
      update_config:
        failure_action: rollback
        parallelism: 1
        delay: 10s
        order: start-first
      rollback_config:
        parallelism: 0 # all rollback simultaneously
        order: stop-first
      restart_policy:
        condition: any
        delay: 10s
        max_attempts: 3
        window: 120s
    networks:
      - host
networks:
  host:
    external: true
    name: host