Home Assistant is a free, open source program for Home Automation. In this guide, I’m going to show you how to install it using Docker on a Synology NAS, with full compatibility with z-wave and network discovery.

There’s a few things you should be familiar with before we get into the nitty-gritty of this.

SSH

You should be familiar with logging into and using SSH. We’ll be using SSH to connect to our Diskstation to run commands on the Linux command line. You’ll see why this is important shortly.

Docker

There’s a whole bunch of information about Docker and how it all works. What containers and images are, all that jazz. I suggest you read up on it to get your head around Docker. It will be worth it, as Docker is [in my opinion] one of the most powerful packages available on Synology products.

In a nutshell, we’ll be using Docker to create a virtual machine (called a container). This container will be running an operating system, that will in-turn run Home Assistant.

Setting Up Your Diskstation

Enable User Homes

Before we dive straight in, there’s three things you’ll need to have set on your Diskstation first.

By default, your Synology allows basic access to the filesystem. Every user that logs into the Diskstation can access the same files as everyone else. “Homes” is a feature which allows each user to have their own home directory. We’ll need to enable this option, as it will enable us to access more areas of the Synology from the file manager.

Login to your Synology NAS from a browser, using the admin account. Under Control Panel -> User -> Advanced. At the bottom, be sure to enable the option Enable User Home Service.

Enable SSH Access

We’ll be logging into the NAS using SSH, so we can perform some Linux commands.

Go to Control Panel -> Terminal & SNMP Be sure the Enable SSH Service is checked.

Install the Docker Package

The Docker package is officially available from Synology, so you should be able to easily find it in the Package Center on your Diskstation.

Once you’ve installed the Docker package, start it. If you’re having issues getting the Docker package to start, check your network settings. I’ve found the Docker will not start if you have an OpenVPN network connection enabled. Disabling the OpenVPN network connection, and then starting Docker should work. Once you have Docker running, you can re-connect the OpenVPN connection to encrypt your traffic again.

The Latest In Your Inbox Enter your email address below to receive my latest blog posts and videos about Home Automation in your Inbox

Logging In via SSH

Now that we have everything setup, it’s time to login to our Diskstation via SSH. I prefer to use a free tool like Putty to do this. Type in the IP Address of your NAS, and the port number specified when you enabled SSH above (default is 22). You’ll then be asked for a username.

DSM 5

I’m running DSM version 5. The latest released version (at the time I’m writing this) is 6. On my version, I need to enter the username root. Using my admin username will not work for what we want to do. So, enter your username as root and the password to your admin account.

DSM 6

If you’re running a newer version of DSM, you may not be able to login using the root username as described above. Instead, you should login using your admin username and password.

Once logged in, use the following command to switch to the root user using the command su - root

Update January 21 2017 User @patflest on the Home Assistant forums has tested these commands with DSM 6, and found that by prefixing the commands with sudo they will work on DSM 6. I’ve updated the commands below to include versions highlighting DSM 6.

Obligatory Caution

You’re now logged into your NAS using the super user account. You are basically in God mode. Although I haven’t heard of it happening, you could potentially brick your NAS if you do something wrong.

Always ensure you check twice before executing any dangerous commands.

Home Assistant Dockerfile

Home Assistant has an official Dockerfile. This is also available from the DockerHub. This will make our lives much easier.

The Dockerfile from Home Assistant will automatically install the Z-wave libraries for us. However depending on whether we want to use Z-wave or not, we’ll need to change the command we need to run to get Home Assistant setup.

Installing Home Assistant without Z-wave

If you don’t want to run Home Assistant and use a USB Z-wave radio, then we don’t need to add any USB devices to our container. From your SSH window, run the following command

Run Home Assistant Docker without Z-Wave (DSM 5) docker run --name home-assistant --restart=always --net=host -itd -v /volume1/Shared/docker/homeassistant/config:/config homeassistant/home-assistant 1 2 3 docker run --name home-assistant --restart=always --net=host -itd -v /volume1/Shared/docker/homeassistant/config:/config homeassistant/home-assistant

Run Home Assistant Docker without Z-Wave (DSM 6) sudo docker run --name home-assistant --restart=always --net=host -itd -v /volume1/Shared/docker/homeassistant/config:/config homeassistant/home-assistant 1 2 3 sudo docker run --name home-assistant --restart=always --net=host -itd -v /volume1/Shared/docker/homeassistant/config:/config homeassistant/home-assistant

Let’s break this command down a bit.

docker run tells Docker to run a container with the parameters we’re parsing.

--name home-assistant The name flag will allow us to easily identify which container is running Home Assistant. This is useful if you use the Docker control panel from the Synology DSM, or when we need to do some commands against the container (like starting, stopping etc)

--restart=always This is a powerful and handy flag to set, especially for Home Assistant. This will tell Docker to keep trying to re-start Home Assistant if it crashes. So, if you’re editing a new automation and make a YAML syntax error (which you will do), you won’t need to open up SSH again to get Home Assistant started once you fix the problem. This is one of the flags you can’t set when using the Docker DSM UI.

--net=host Another important and powerful flag. We need to make sure Home Assistant has full access to our local network. We’ll need this for network discovery to work. This will allow Sonos, Hue, Plex etc to be discovered on the network automatically. This is one of the flags you can’t set when using the Docker DSM UI.

-itd This is actually three commands in the one. The important one is d. This tells Docker to run in detached mode. Once Docker runs the container, our SSH session is returned to us. If we don’t specify this, we’ll see the output from Home Assistant in our SSH console. Also import is the t, which tells Docker to tag the container for future use.

-v /volume1/Shared/docker/homeassistant/config:/config Here we’re creating a folder on our NAS to keep the Home Assistant configuration files. You can place it in any folder you like. I’ve chosen here to place it in a folder called Shared, which I can access from my local network easily. Whatever you choose to use, the folder must exist before you will be able to start Home Assistant. If you want to use the same folder as I did above, you can create it by running mkdir -p /volume1/Shared/docker/homeassistant/config

homeassistant/home-assistant Finally this tells Docker which container to lookup on DockerHub.

Once we run this command, Docker will begin to start downloading all the files Home Assistant needs, such as the operating system, Python, and Z-wave.

Once everything has been installed (it could take some time the first go around), you should be able to access Home Assistant at the IP address of your NAS. For example, my NAS is at 192.168.1.3, so I can access Home Assistant by going to http://192.168.1.3:8123. The last part of the address tells the browser to connect to port 8123, which Home Assistant listens to.

Installing Home Assistant with Z-wave

Installing Home Assistant with support for Z-wave on your Synology NAS is basically the same as above, however there are a couple of other flags we need to add to our command.

Before we begin, we first need to plug in our Z-wave USB radio into the NAS. I’m using an Aeotec Z-stick.

Once your Z-wave radio is plugged in, we need to find out the path to the radio. When you plug any USB device into your NAS (or any Linux system), it is given a filepath that you can use to access it. On Synology, our USB path is stored in the /dev/ folder, so let’s try and find our USB stick in there. Using a SSH window, we can run the following

Find USB devices attached to Synology ls /dev/tty* 1 2 3 ls / dev / tty *

The above command should show you any USB devices plugged into your NAS. If you have more than one, you may get multiple items returned. For myself, I have the following USB devices plugged in.

ttyUSB0 1 2 3 ttyUSB0

As this is the only device I have plugged into my NAS, I can safely assume that this is my USB radio. If you have more than one device returned, I suggest you unplug your radio, re-run the ls command above, and see which number is missing. This will be your z-wave USB Radio.

If the ls command above didn’t return any USB devices for you, its possible your system is assigning them another name.

Now that we have our USB radio filepath, we can setup our Docker container. Let’s slightly change our docker run command from above, to include some more parameters.

Run Home Assistant Docker with Z-Wave (DSM 5) docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 homeassistant/home-assistant 1 2 3 docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 homeassistant/home-assistant

Run Home Assistant Docker with Z-Wave (DSM 6) sudo docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 homeassistant/home-assistant 1 2 3 sudo docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 homeassistant/home-assistant

--privileged Gives the container some higher access rights. Usually this isn’t necessary, however I’ve included it because I trust Home Assistant, and want to ensure it has access to the USB on the host without any permission issues. Remember, as we’ve only included the config directory in the -v flag, the Home Assistant container won’t be able to access anything outside of that directory on the NAS. So there’s not much harm that it can do outside of that folder.

--device The magic flag that will link the USB Radio into the Home Assistant machine/container. When the Home Assistant machine/container boots up, it will have a USB device available at /dev/ttyUSB0.

Now that we’ve got our new Docker command setup, we also need to enable Z-wave on Home Assistant. Let’s edit our configuration file and add the following.

configuration.yaml zwave: usb_path: /dev/ttyUSB0 1 2 3 4 zwave : usb _ path : /dev/ttyUSB0

That will tell Home Assistant where to look for our Z-wave radio.

Adding a Bluetooth Radio

I also have a USB Bluetooth Radio plugged into my Diskstation. However, it doesn’t come up using the command above. Instead, if you’d like to use the Bluetooth device tracker, you can use the following flag to give Home Assistant access to that device.

-v /dev/bus/usb:/dev/bus/usb 1 2 3 -v /dev/bus/usb:/dev/bus/usb

So, if you want to enable Z-wave and Bluetooth in Home Assistant, your new Docker run command looks like

Run Home Assistant Docker with Z-Wave and Bluetooth (DSM 5) docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 -v /dev/bus/usb:/dev/bus/usb homeassistant/home-assistant 1 2 3 docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 -v /dev/bus/usb:/dev/bus/usb homeassistant/home-assistant

Run Home Assistant Docker with Z-Wave and Bluetooth (DSM 6) sudo docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 -v /dev/bus/usb:/dev/bus/usb homeassistant/home-assistant 1 2 3 sudo docker run --name home-assistant --restart=always --net=host --privileged -itd -v /volume1/Shared/docker/homeassistant/config:/config --device /dev/ttyUSB0 -v /dev/bus/usb:/dev/bus/usb homeassistant/home-assistant

Of course, we’d also need to enable the Bluetooth tracker in Home Assistant, so we’d add the following to our Home Assistant configuration.

configuration.yaml device_tracker: - platform: bluetooth_tracker 1 2 3 4 device _ tracker : - platform : bluetooth_tracker

Upgrading Home Assistant

One of the great things about Home Assistant is their rapid development time. There’s usually a new release of Home Assistant out every 2 weeks. Which is very impressive.

When it comes time to upgrade your version of Home Assistant, we need to login via SSH again. This time we’ll want to do the following.

docker stop home-assistant Stop Home Assistant from running. docker rename home-assistant home-assistant-old We’ll rename our current Home Assistant container to something memorable. This way, if there’s an issue with the new version of Home Assistant it’s easy to roll-back. docker pull homeassistant/home-assistant Tell Docker to fetch the latest version of Home Assistant. docker run --name home-assistant --restart=always --net=host -itd -v /volume1/Shared/docker/homeassistant/config:/config homeassistant/home-assistant Re-run the command we used to build Home Assistant in the first place. (Command above is if we didn’t use Z-wave)

Some things to watch out for

I’ve been using Home Assistant on my Synology for a few months now. Here’s a few things I’ve noticed that may help you.

Disable any OpenVPN Connections when starting Docker

The Docker Package on Synology DSM can’t be started if you have an OpenVPN connection open. When trying to start Docker, your Diskstation will hang, and then fail to start the Docker package. Disabling the OpenVPN connection, then starting Docker should fix this. Once Docker is running, you can turn your OpenVPN connection back on.

Must use the root user

To perform the docker commands in this blog post, you must use the root user from SSH. Using any other account (even the admin account) just won’t work. Unless of course you’re using DSM 6, which you can use the admin account if you prefix all docker commands with sudo.

Home Assistant with Z-wave Radio won’t start after NAS Reboot

This is a frustrating issue I’m yet to solve. When your Synology Diskstation reboots for any reason (you shut it down, there was a power failure), the Home Assistant Docker won’t be able to boot because the USB attached to the NAS has stopped responding.

To fix this, I usually have to do the following steps

Remove the USB Radio from the NAS USB port. Then plug it back in. If Home Assistant still won’t start, I open up an SSH connection as root, and perform the following command

rm - rf / dev / ttyUSB0 WARNING: That is a very dangerous command to perform. I have had no issues doing this with my Aeotec Z-stick, but please be careful! Remove the USB Radio from the NAS, and plug it back in

After performing those steps, my Home Assistant container will boot up again. A UPS for the NAS might be a good investment in the future.

Where to Next

Now that you’ve got Home Assistant up-and-running, its time to start setting up your automated house. Be sure to checkout the Home Assistant Website and of course forums! The Home Assistant community is friendly, and always happy to help!