Home Assistant on NAS via Docker: Setup Guide

Home Assistant is the most capable open-source home automation platform available. It integrates with over 3,000 smart home devices across every major protocol, runs entirely locally without cloud dependencies, and has an active community producing integrations for virtually any device. Running Home Assistant in Docker on a NAS is a practical approach for users who want to consolidate services on existing hardware without dedicating a Raspberry Pi or separate machine. This guide covers the Docker-based Home Assistant Container deployment on Synology and QNAP, including the critical network mode requirement for local device discovery.

Home Assistant Container vs Home Assistant OS

Home Assistant comes in several deployment forms. For NAS Docker use:

• Home Assistant Container (this guide): Runs the Home Assistant core in a Docker container. All integrations work. The Supervisor add-on system is NOT available. No add-ons like ESPHome flash tool, Mosquitto MQTT broker, or the Z-Wave JS UI. These must be run as separate containers alongside Home Assistant
• Home Assistant OS: A full Linux OS designed to run on dedicated hardware (Raspberry Pi, x86 mini-PC). Includes the Supervisor and add-on system. Runs in a VM on NAS via QNAP Virtualisation Station or Synology Virtual Machine Manager. More overhead but full feature parity with dedicated hardware

If you primarily use cloud-based integrations (Hue, Nest, Ring via cloud APIs), Home Assistant Container on Docker is sufficient. If you want local Z-Wave/Zigbee coordination, MQTT broker, or ESPHome all managed from within Home Assistant's UI, run Home Assistant OS in a VM for the full Supervisor experience.

Step 1: Deploy Home Assistant Container

Create a Docker Compose file at /volume1/docker/homeassistant/docker-compose.yml (Synology) or /share/docker/homeassistant/docker-compose.yml (QNAP):

version: '3.8'
services:
  homeassistant:
    container_name: homeassistant
    image: homeassistant/home-assistant:stable
    network_mode: host
    environment:
      - TZ=Australia/Sydney
    volumes:
      - ./config:/config
    restart: unless-stopped
    privileged: true

Key points in this Compose file:

• network_mode: host. Uses the NAS host network directly. Required for device discovery (mDNS, SSDP, Bluetooth). Without this, Chromecast, Apple TV HomeKit, and ESPHome device discovery will not work
• privileged: true. Needed for USB device access (Zigbee/Z-Wave sticks). Can be removed if you have no USB-connected devices
• TZ=Australia/Sydney. Set to your timezone for correct automation timing

Deploy with docker compose up -d. Home Assistant starts at http://[NAS-IP]:8123. Initial startup takes 1-2 minutes.

Step 2: Initial Configuration

On first access at http://[NAS-IP]:8123:

1. Create your Home Assistant account (name, username, password)
2. Set your home location. This is used for sun-based automations (sunset, sunrise triggers)
3. Home Assistant's onboarding wizard auto-discovers devices on your network. Accept or skip discoveries as appropriate
4. After onboarding, go to Settings → Devices & Services → Integrations to add the services and devices you want to control

Home Assistant will continue discovering new devices in the background as you add smart home hardware. Check the Integrations page periodically for auto-discovered devices.

Step 3: Add Companion Containers

With Home Assistant Container (no Supervisor), services that would normally be Home Assistant Add-ons need to run as separate Docker containers:

Mosquitto MQTT broker. Required for MQTT-based devices (Zigbee via Zigbee2MQTT, DIY sensors):

  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    ports:
      - 1883:1883
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
    restart: unless-stopped

Add this to the same Compose file as Home Assistant. Configure Home Assistant's MQTT integration to point to your NAS IP on port 1883.

Zigbee2MQTT. For Zigbee device coordination via a USB Zigbee dongle (ConBee II, HUSBZB-1). Requires passing the USB device through to the container. Follow the Zigbee2MQTT documentation for the specific device path on your NAS.

Step 4: Remote Access

Home Assistant has built-in remote access options:

Nabu Casa (Home Assistant Cloud, $7.50 USD/month): Official cloud remote access and Alexa/Google Assistant integration. Simple, no port forwarding required, supports CGNAT. Subscription revenue funds Home Assistant development.

NGINX Proxy Manager + HTTPS: Same setup as Nextcloud/Vaultwarden. Add a proxy host in NPM for port 8123 with Let's Encrypt HTTPS. Works without Nabu Casa for remote access, requires open ports or Cloudflare Tunnel.

Cloudflare Tunnel: Free, works behind CGNAT, zero open ports. Run the Cloudflare Tunnel daemon as a Docker container alongside Home Assistant.

The Home Assistant Companion app (iOS and Android) handles remote access transparently. It connects via local IP when on your home network and switches to the external URL when away.

🇦🇺 Australian Users: Device Compatibility Notes

Most major smart home ecosystems sold in Australia are fully supported by Home Assistant:

• Philips Hue: Local API integration, no cloud dependency. Auto-discovered on local network
• Tuya/Smart Life devices: Millions of cheap AU smart home devices use Tuya. Home Assistant's local Tuya integration works without cloud via the local control API
• Google Nest / Chromecast: Discovered via mDNS (requires host network mode). Nest Hub, Chromecast, and Google Home speakers integrate well
• Apple HomeKit: Home Assistant can act as a HomeKit bridge. Expose all your non-HomeKit devices to Apple Home via Home Assistant's HomeKit Controller integration
• Shelly: Excellent Home Assistant support via local MQTT or REST API. Popular in AU for retrofitting existing light switches

AU energy providers: Home Assistant has Amber Electric, Origin, and AGL integrations available. Enable dynamic pricing automations (run dishwasher when spot price is low) if on a compatible energy plan.

Related reading: our NAS buyer's guide.

Related reading: our NAS explainer.