Installing Home-Assistant.io on a Synology Diskstation NAS

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

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

Enable User Homes

Enabling User Homes in DSM 5

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.

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

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

Shell

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.

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.

--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

YAML

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.

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

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

YAML

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-assistantStop Home Assistant from running.

docker rename home-assistant home-assistant-oldWe’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-assistantTell 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-assistantRe-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 userTo 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 RebootThis 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 commandrm-rf/dev/ttyUSB0WARNING: 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!

Excellent write up and I’m really appreciative that you shared it. Still, I have some questions:

1) How up to date are these instructions regarding the latest releases?
2) Do you perform backups of your installations and, if so, how?
3) Ever figure out the Z-wave reboot issue? That sounds pretty irritating.

Regardless, I’ll certainly be referencing this as I do an install on my DS214play.

1) As mentioned in the post, this is for DSM 5. The only difference I am aware of is how you access root as explained above. All other commands are then just simple docker commands, which haven’t changed since I posted this. So anything starting with docker should be accurate, no matter what version of DSM you’re using.

2) I currently have my Synology NAS set to RAID over the harddrives. Once a week, a complete system backup is taken, but also stored on the NAS. For HASS configuration, I have copies on my computer, which I use as my “master” then copy over to the NAS. I haven’t currently got a proper offsite automated backup in place. Something to look into I guess!

3) Nope, still no clue on that one. However since posting this I’ve rebooted my NAS a couple of times, and interestingly not faced the same issue. So I’m hoping Synology have fixed it in one of the security updates I’ve installed, or I’ve just been lucky.

On DSM 6 (or greater), su - root does not work. I had to use sudo -i after logging as admin. Also, it will be nice to note that the user needs to ensure that the path /volume1/Shared/docker/homeassistant/config exists before running the command (I had to manually create the directory).

Good point about the path needing to exist! I’ve added a note for that 🙂

Scott Bradshaw

If you are using secure Z-wave devices (ex: Locks), you will need to add a Network Key to options.xml file, and map this. As of 0.39, the mount path is /usr/local/lib/python3.5/site-packages/libopenzwave-0.3.2-py3.5-linux-x86_64.egg/config/options.xml

Interesting. I used to use a network key for my setup, as I was having issues with powered devices being marked as dead (there’s a thread on the Home Assistant forums about it).

When I used that, from memory I just placed by options.xml file in the same folder where my Home Assistant configuration.yaml file was placed. Hopefully it’s still the same in the latest versions.

Scott Bradshaw

Hmm. This is not what the HA zwave documentation says. The file goes in the openzwave config_path – not the HA config path. I also believe I originally tried this, and it didn’t work. When I upgraded to 0.39, the libopenzwave path changed, and my network key didn’t get mapped. When this happened, the lock stopped working. The worst part was even after correcting the config.xml path in Docker, the lock STILL didn’t work. It seems like whenever an invalid key is tried, the lock will refuse to work again with the controller for security reasons? Not sure. I had to remove node and add secure node again. For the lock, it was a pain, because it requires you open the lock and pull out the zwave component and put it 12 inches away from the controller. Such a pain!

Ugh no that sucks! However, I guess as its a lock it’s probably a good thing that it requires you to re-link, incase of a security breach.

Thanks for the heads up and info where to put the options.xml file!

Jaysen Polanco

Phil,

Thanks for the tutorial, very easy to follow… however I am having one slight problem… I am running DSM6 and using sudo commands… when attempting to run with Z-wave, I’ve followed your steps – replacing ttyUSB0 to ttyACM0 – and once it downloads and extracts, I get the following error;

“docker: Error response from daemon: stat /volume1/shared/docker/homeassistant/config: no such file or directory.”

In my shared folder, I do have a Docker subdirectory with a homeassistant folder. Any ideas?

EDIT: Disregard.. I read a few post down that the folder had to be manually created in DSM6. All is well now!

André van Stijn

Good morning Phil,

Thank you for this clear tutorial, did you make any progress on “Home Assistant with Z-wave Radio won’t start after NAS Reboot”?

Yeah, I found I needed to perform the rm commands in the article, before unplugging the radio and plugging it back in. Interestingly, no matter which port I used, it always came up to the same /dev/tty address. However, changing ports is worth a try!

So the installation directory is “/volume1/Shared/docker/homeassistant/”

So I created the www map as follows “/volume1/Shared/docker/homeassistant/www” and put the jpg inside it the I used the pictur: /local/picture_name.jpg line in the known_devices.yaml, but this is not working, what am I doing wrong? I tried a png and a jpg file neighter one of them are showing up.

Hope you can help me out with this. I followed your instruction here to get HA install on my Synology Nas. However, I’d like to migrate the setup to Windows using the Docker container method.

I followed the HA installation instruction using –net=host and also tried Bridge mode but neither way could get the “Discovery” component working. I had to use a manual configuration yaml to get all of my devices populate.

Beside this “Discovery” issue, everything else is working properly under either –net=host or bridge mode… Would you have any idea on how to get this going on Windows?

Hmm I am not sure on this one. I think there’s a lot of Docker + Windows issues that could potentially cause this.

According to the Discovery Component Docs there are a couple of known issues on Windows. The one that sticks out to me is

If you are on Windows and you’re using Python 3.5, download the Netifaces dependency

Home Assistant recently upgraded the Docker images to Python 3.6. So I am not sure if this applies. However, I would suggest trying to install that Netifaces dependency inside the container. You can open a bash console to the container

1

2

3

4

5

6

docker exec-it home-assistant/bin/bash

Then follow the instructions to install that Python dependency using pip.

I don’t know if this will help, but at least its something for you to try. Best of luck!

Hilman Chung

Thanks but no luck…

On the other hand, would you know how run docker and home-assistant off a usb drive on the Nas? My ultimate goal is really just to let the HDDs hibernate more often.

It may not be /usbshare1, so take a look around the file system to see what the file path might be. If not I’m sure Google will be able to find the path. Then its just a matter of adjusting the run command above to the path where your USB files are.

Let me know how you go. Would be interested to hear if running it from a USB does indeed allow your harddrives to hibernate.

Cheers

Hilman Chung

Thanks Phil,

I tried getting USB running…. Couple of issues – 1. It seems the USB path is not persistent after stopping and starting HA, after a restart of the container, HA cannot find the Config path…. 2. I think this still won’t allow for hibernation to happen because the container itself is still running on Volume1.