Running Home Assistant Container on Synology NAS Storage

Home Assistant Container NAS storage solves a simple problem in Realm Labs: the container itself can remain disposable while the important configuration stays persistent, visible and easy to back up.

Home Assistant Container runs through Portainer on the Synology infrastructure, with its /config directory bound to persistent storage on Seido, the Synology DS224+ at the centre of the lab. That means I can recreate or update the container without losing automations, dashboards, integrations or the YAML files behind them.

This guide documents the layout I use, why I chose it, the distinction between local NAS storage, SMB and NFS, and the checks that matter before trusting the setup.

Home Assistant Container NAS Architecture

• Application: Home Assistant Container
• Container management: Docker and Portainer
• Persistent configuration: Synology volume mapped to /config
• Desktop access: the same folder exposed to Windows through SMB
• Networking: host mode so local discovery works normally

The important point is that SMB is not being mounted inside Home Assistant. The container sees a normal host path. SMB simply gives me a convenient way to reach those files from a Windows PC.

Why I Chose Home Assistant Container

Home Assistant OS is the recommended installation for most people because it manages more of the platform for you. Home Assistant Container is different: it runs Home Assistant Core inside a container environment that you maintain yourself, and it does not provide the Home Assistant add-on system.

For Realm Labs that trade-off made sense. Docker, Portainer, shared storage, monitoring and backups were already established. I wanted direct control of the container, its network mode and its persistent data rather than another separately managed appliance.

If you specifically want Supervisor-managed add-ons, this is not the right installation method. If you already operate Docker and are comfortable managing companion services as separate containers, it is a clean fit.

Planning the Persistent Configuration Folder

Home Assistant stores its configuration, automations, dashboards, integration data, secrets and default SQLite database beneath /config. Losing that directory means rebuilding the installation, so the bind mount is the most important part of the deployment.

On Seido, the folder sits beneath the Docker-volume structure:

/volume1/<your-share>/docker-volumes/homeassistant

Create the directory before deploying the stack and confirm that the account used by Docker can read and write it. Avoid blindly changing ownership across a Synology volume: UID and GID choices may affect other services using the same share. If permissions fail, diagnose the exact container user and folder permissions first.

Deploying the Container in Portainer

I deploy Home Assistant as a Portainer stack. The Compose file below follows the current Home Assistant Container pattern while leaving the Synology path as a placeholder for your own volume.

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - /volume1/<your-share>/docker-volumes/homeassistant:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      TZ: Europe/London
    network_mode: host
    restart: unless-stopped
    stop_grace_period: 60s

The official Linux container example also includes privileged mode and a read-only D-Bus mount for integrations such as Bluetooth. I do not add permissions simply because an example contains them: expose only the host devices and capabilities your installation actually needs.

Why host networking matters

Home Assistant uses local discovery protocols that do not always behave well through an ordinary bridged Docker network. With network_mode: host, the container uses the host network directly and Home Assistant becomes available on port 8123.

http://<SYNOLOGY-IP>:8123

Host networking also means there is no separate ports: mapping in the Compose file. Adding both is unnecessary and can make troubleshooting more confusing.

Why I added a 60-second stop period

Docker normally allows a limited time for a container to stop. Home Assistant may need longer to close its SQLite database cleanly, especially on a busy installation. A stop_grace_period of 60 seconds gives it time to finish without forcing every restart to wait for a full minute—the container exits as soon as shutdown completes.

Starting and Checking Home Assistant

After deploying the stack, I check three things before starting the onboarding wizard:

1. The container remains running rather than entering a restart loop.
2. The Synology folder begins filling with files such as configuration.yaml, automations.yaml and home-assistant_v2.db.
3. The web interface opens at the host address on port 8123.

If the container repeatedly restarts, the first place to look is the Portainer log. Permission errors, an invalid path and a port or networking conflict are easier to understand there than from the browser.

Editing configuration.yaml Safely

Because the configuration directory is visible through SMB, I can open it from Windows using a path such as:

\Seido<share-name>docker-volumeshomeassistant

This is useful, but convenient access also makes it easy to introduce a bad edit. My normal sequence is:

1. Copy the current file or take a configuration backup.
2. Edit with a YAML-aware editor so indentation remains visible.
3. Use Home Assistant’s configuration check where available.
4. Reload only the affected integration when possible; restart the container only when required.
5. Check the logs immediately after the change.

SMB, NFS and the Source of Confusion

The original version of this guide treated SMB and NFS as if they were interchangeable parts of the container mapping. They are not.

• Local Synology path: used by a container running on the NAS itself.
• SMB: useful for Windows access to the same files.
• NFS: useful when a separate Linux, Raspberry Pi or Proxmox host needs to mount Synology storage.

If Docker runs on another machine, mount the NFS share on that host first and bind the resulting local mount point into /config. Be aware that putting Home Assistant’s live SQLite database on remote storage introduces a dependency on network availability, latency and filesystem behaviour. For that design, test shutdowns and recovery carefully or consider keeping the live database local while backing up the configuration to the NAS.

Backups Before Updates

The container image is replaceable; the configuration directory is not. Before a major update I preserve the full /config directory, including hidden storage used by integrations. Copying only the visible YAML files is not a complete backup.

My safe update sequence is:

1. Review the Home Assistant release notes and breaking changes.
2. Take or verify a current backup of /config.
3. Pull the new stable image in Portainer.
4. Recreate the container using the same persistent mapping.
5. Open the logs and verify integrations, automations and dashboards.

Troubleshooting the Common Failures

The container starts but /config is empty

Check the host side of the bind mount. A typo can cause Docker to create a new empty directory, leaving Home Assistant apparently working but storing data somewhere you did not intend.

Permission denied errors

Confirm the Synology folder permissions and the identity used by the container process. If the storage is mounted through NFS on another host, also check the export rule, squash behaviour, UID/GID mapping and NFS version. The related guide on fixing Docker permissions on a Synology NFS share covers that problem in more detail.

Home Assistant opens but devices are not discovered

Verify that the stack is using host networking and that the NAS firewall allows the required local traffic. USB radios also need the correct device exposed to the container.

Database warnings after a restart

Look for evidence that Docker forced the container to stop before Home Assistant closed its database. Recreate the service with the longer stop grace period, then confirm that subsequent shutdowns are clean.

Hardware Used in Realm Labs

The installed storage platform for this project is a Synology DS224+. Seido provides the persistent Home Assistant configuration as well as shared storage for other Docker services and infrastructure around the lab. The current equivalent listed on the Realm Labs Hardware page is the Synology DS225+.

What I Would Keep—and What I Would Change

I would keep the separation between the replaceable container and persistent configuration. It makes upgrades, recovery and inspection far easier, and it fits the wider Realm Labs approach to Docker and Portainer.

I would also keep SMB access for administration, but I would avoid describing the live bind mount itself as SMB or NFS when the container is running directly on Synology. That distinction matters when troubleshooting permissions and performance.

For a new user who wants the simplest supported experience and managed add-ons, I would point towards Home Assistant OS. For an existing Docker environment where the operator already manages storage, networking and updates, Home Assistant Container remains a controlled and understandable option.

The Result

Home Assistant now fits into Realm Labs as another maintainable service rather than a special appliance. The container can be recreated, the configuration remains on Seido, the files are accessible from Windows, and the backup boundary is obvious.

You can explore the wider Home Assistant and smart-home archive, see how Synology provides the storage backbone, or read about Home Assistant at the heart of Realm Labs.

For the current upstream container requirements and Compose example, refer to the official Home Assistant Linux installation documentation.