LinuxcontainersTested on real hardware

Home Assistant Container on a NAS (docker-compose)

Deploy Home Assistant Container on a NAS with docker-compose: pinned image, host networking for discovery, and companion-service stubs kept commented.

DistrosAny NAS/Linux host with Docker + Compose
Shellbash
Updated
Script
bash
# Home Assistant Container on a NAS — docker-compose deploy.
# Run from the directory where you keep this compose file.
#
# 1) Create the config directory (adjust the /volume1 path to your NAS):
mkdir -p /volume1/docker/homeassistant/config

# 2) Write docker-compose.yml with this content:
cat > docker-compose.yml <<'YAML'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:2026.8.1
    network_mode: host          # required for mDNS/SSDP discovery
    restart: unless-stopped     # use "always" if a manual stop should NOT survive a reboot
    environment:
      TZ: America/Chicago
    volumes:
      - /volume1/docker/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    # Attaching a USB Zigbee/Z-Wave stick later? Uncomment and map it:
    # privileged: true
    # devices:
    #   - /dev/serial/by-id/usb-YOUR_COORDINATOR-if00:/dev/ttyUSB0

  # Companion services stay commented until the hardware/credentials exist.
  # Each is its own container, so an HA restart never drops the Zigbee mesh:
  # mosquitto:      # MQTT broker  -> https://mosquitto.org
  # zigbee2mqtt:    # needs a USB Zigbee coordinator -> https://www.zigbee2mqtt.io
  # zwave-js-ui:    # needs a Z-Wave stick -> https://github.com/zwave-js/zwave-js-ui
  # matter-server:  # Matter controller
YAML

# 3) Bring it up and follow the first boot:
docker compose up -d
docker compose logs -f homeassistant

# 4) Open http://YOUR_NAS_LAN_IP:8123 and create the owner account NOW
#    (an unclaimed instance is anyone's to claim).

What this does

Deploys Home Assistant using the Container install method (plain Docker, no Supervisor or add-on store) on a NAS or any Linux host that already runs Docker Compose. The three lines that matter are the pinned image tag, network_mode: host (so mDNS/SSDP discovery can see your LAN), and the restart policy. Companion services (MQTT, Zigbee2MQTT, Z-Wave JS UI, Matter) ship commented — you enable them only when the matching USB radio or credentials exist.

Full reasoning, the placement decision (NAS vs offsite cluster), remote access, and monitoring wiring are in the companion post: Home Assistant on a NAS: Why Placement Beats Hardware.

Prerequisites

  • A NAS or Linux host with Docker Engine and the Compose plugin installed.
  • The host on the same LAN as your smart devices — discovery and USB radios do not cross a VPN tunnel.
  • For Zigbee/Z-Wave later: a USB coordinator plugged into this host.

Notes

  • Make these values your own before you run anything:
    • /volume1/docker/homeassistant/config → your NAS config path (Synology/Asustor use a /volume1 root; adjust to yours).
    • TZ: America/Chicago → your timezone.
    • 2026.8.1 → the current stable Home Assistant release when you deploy (the tag is pinned on purpose — bump it by hand after reading the release notes).
    • YOUR_NAS_LAN_IP → your NAS’s LAN address.
    • usb-YOUR_COORDINATOR-if00 → the real by-id path of your radio, only when you uncomment that block.
    • Rule of thumb: if a value looks specific to one machine, it’s a placeholder to change — not a literal to copy.
  • network_mode: host has a side effect: the container reaches other containers by localhost:PORT, not by container name. Plan companion services (a broker on localhost:1883, for example) accordingly.
  • Updating: docker compose pull homeassistant && docker compose up -d. Read the release notes first — monthly releases occasionally carry breaking changes.
  • Lost the admin password? Home Assistant’s offline reset (hass --script auth … change_password) keeps the account and long-lived tokens. Run it interactively, never from a shared transcript.
All playbooks