Installing Home Assistant

Running Home Assistant on a NAS or Docker (with Portainer)

Run Home Assistant on a NAS or in Docker with Portainer: compare a VM with a container, use a Compose file with host networking, and keep config safe.

On this page
  1. Two ways to run Home Assistant on a NAS
  2. Option A: Home Assistant OS in a VM
  3. Can I run Home Assistant on a Synology NAS?
  4. Option B: Docker Compose
  5. Deploying with Portainer
  6. Synology Container Manager
  7. QNAP Container Station
  8. Radios on a NAS
  9. Updating and backing up
  10. Security

Two ways to run Home Assistant on a NAS

  1. Home Assistant OS in a VM. The NAS runs a virtual machine with HAOS. You keep the Supervisor, the add-on store and USB passthrough for radios. Allocate about 2 vCPUs, 2 GB or more of RAM and 32 GB or more of storage.
  2. Home Assistant Container. The NAS runs the Home Assistant image in Docker with host networking. It’s lightweight, but it has no Supervisor and no add-on store. Other services, such as an MQTT broker or Zigbee2MQTT, run as separate containers.

Choose the VM if you want add-ons. Choose the container if you already run Docker and don’t need add-ons.

Option A: Home Assistant OS in a VM

Use your NAS’s VM app: Synology Virtual Machine Manager, QNAP Virtualization Station, or the VM feature on Unraid or TrueNAS SCALE. The image and firmware settings are the same as in the VM setup guide. If your NAS app supports USB passthrough, add your radio to the VM’s settings.

Can I run Home Assistant on a Synology NAS?

Yes, on models with an x86-64 CPU and Virtual Machine Manager. Plus-series models such as the DS224+ and DS423+ support it. Value and j models use ARM CPUs and don’t include Virtual Machine Manager. Container Manager is also available on many x86-64 models. Check your model’s specifications before you buy or install.

Option B: Docker Compose

Compose is a clear way to define a container, and it’s the same file a Portainer stack uses. Save this as compose.yaml:

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    environment:
      TZ: Europe/London
    restart: unless-stopped
    stop_grace_period: 60s
    network_mode: host
    privileged: true # Included in the official example; see the note below

Start it with docker compose up -d, then open http://<host-IP>:8123.

What each setting does:

  • /PATH_TO_YOUR_CONFIG:/config stores your configuration on the host. Back up this folder.
  • network_mode: host lets Home Assistant discover devices over mDNS and other broadcast protocols. Bridge networking with port 8123 mapped usually breaks discovery.
  • TZ sets the time zone. Use your own time zone name.
  • stop_grace_period: 60s gives Home Assistant time to close its database. Docker’s default is 10 seconds, and a shorter stop can leave the database unclean and cause warnings on the next start. If you change this value on an existing container, run docker compose up -d again so the container is recreated.
  • privileged: true is in the official example, but it gives the container broad access to the host. Use it only with trusted images. If you’d rather not, remove it and map only the radio device, as shown below.
  • restart: unless-stopped brings the container back after a reboot.

To give the container one serial radio without privileged, add a device mapping under the service:

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

Check the device path on the host first, because it can change. Pin a specific version tag instead of stable if you want controlled updates.

Deploying with Portainer

  1. In Portainer, open Stacks, then select Add stack.
  2. Give the stack a name, paste in the Compose file, and select Deploy the stack.
  3. When the container is running, open its page in Portainer to check the logs.

A few Portainer details matter:

  • Keep host networking, or discovery will break.
  • Map /config to a host folder you can back up.
  • Set TZ to your local time zone.
  • To update, pull the new image and recreate the container. Your /config folder stays in place.
  • Don’t publish Portainer’s port to the internet. It’s an admin tool.

Synology Container Manager

Install Container Manager from Package Center. Then:

  1. In Registry, search for homeassistant/home-assistant and download the stable tag.
  2. In Image, run the image. In the advanced settings, add a shared folder and mount it at /config.
  3. Add an environment variable named TZ with your time zone.
  4. Set the network to host, then finish the wizard.
  5. Open http://<NAS-IP>:8123. If you use the Synology firewall, allow port 8123.

QNAP Container Station

Install Container Station, then use Create to search for homeassistant/home-assistant and pick the stable version. Mount a shared folder at /config, set the network mode to Host, and add a TZ variable. Some ARM-based QNAP models have had trouble with Container Station 3. In that case, use the Compose approach above.

Radios on a NAS

Synology DSM lacks many USB serial drivers, so Zigbee and Z-Wave sticks often need extra drivers or a network-attached coordinator. Confirm the NAS can see the stick before you map it into the container. Then use the devices: setting shown above.

Updating and backing up

  • Container: pin a version tag, and update by pulling the new image and recreating the container.
  • VM: take a snapshot before you update.
  • Both: back up the /config folder, and keep Home Assistant’s own backups on another device. A NAS is a single point of failure, so a reboot or update takes Home Assistant down with it.

Security

Keep the NAS admin page, Portainer and Home Assistant off the public internet. For remote access, use a VPN. Use only trusted container images, and remember that privileged: true grants broad access to the host.

If you’re still choosing a NAS, see which NAS is best for running Home Assistant. If a small dedicated box makes more sense, compare the options in how to install Home Assistant.

The complete guide to installing home assistant

How to Install Home Assistant: Every Self-Hosted Method Compared
Read the guide

Keep exploring

Guides from other topics

All topics →