Installing Home Assistant on a QNAP NAS using the CLI and Docker Compose

Community Guides
1

These instructions show how to use a command-line (CLI) and Docker Compose to install Home Assistant on a QNAP NAS. GUI based instructions are available under Home Assistant’s “Getting Started” section here. If you are brand new and just want to get up and running, go with the GUI instructions. Eventually, if you stick with Home Assistant, or plan to run more containers, you’ll probably find the process below to be a quicker and more efficient method to maintain and update containers on your device.

Prerequisites

  1. Install Container Station on your QNAP device if you haven’t already. Docker support is embeded in this package and therefore still required.

  2. Update network settings on your QNAP to allow direct connections from your local device (i.e. laptop, desktop, etc).

    • Visit: Control Panel => Telnet/SSH:
      • Check 'Allow SSH connection" if it is not already enabled.
        • This will be used to login to your NAS using a command line tool
    • Visit: Control Panel => Win/Mac/NFS:
      • Choose the option(s) relevant to your device OS. More detail here
        • This allows your local device to make network connections to your NAS so that the files there can be directly viewed/edited from your local machine (note: you will likely have to setup certain user permisions if you haven’t already done so).

  3. Test Connections

    • Using the Terminal app on a Mac or Linux, or PowerShell in Windows, try to login to your NAS. Basic syntax at the prompt is ssh user@IP-Address, for example: ssh [email protected]
    • Verify you can access the content on your NAS from the file manager program on your local device. I am on Windows 10 and in the left navigation panel of File Explorer I can see the name of my QNAP device Hoth listed under the Network section. Selecting that entry will then show the folders I have access to in the right panel.

  4. Install VSCode or similar text editor on your local device. This will be used to edit the Docker Compose file, and later, Home Assistant files if you choose.

Make storage location decisions

We’re almost to the actual install, but first there are two decisions you’ll need to make:

  1. Where on your NAS do you want to store Home Assistant’s persistant data? This is the permanent data that survives between container updates.
    • For demonstration purposes, I am going to choose to create a new Shared Folder on the QNAP device. I’ll name the folder dockerand then create a sub-folder for Home Assistant inside that. We end up with a new path looking like: docker/home_assistant. This is a convenient directory structure if you plan on running multiple containers. If not, naming the Shared Folder home_assistant instead of docker could work just as well.
    • Go ahead and create the folder(s) once you’ve decided on a storage location.
  2. You also need to decide where you want to keep the Docker Compose file we’ll be creating in the next stage. The file itself is tiny, but you may need to access it with some frequency, so a convenient place is recommended.
    • I keep mine under homes/username of my username in QNAP. If my username was mark, then the path would be homes/mark. This is convenient because when I log into the device via SSH, I do not need to specify an additional path to the file when I run docker compose (example is below).

Setup and start Home Assistant

Final stretch:

  1. Create a Docker Compose file - this is just a text file with a .yml or .yaml extension that tells Docker which image to pull and how to configure a container to run the image.

    • If you name the file ha_install the full filename would be ha_install.yml. Using the path I mentioned above, the path and filename would be homes/mark/ha_install.yml.
    • This can be created via CLI or a text editor, whichever you prefer.

  2. Using a text editor, open the file and paste these contents:

    	version: '3'
	services: 
		homeassistant:
			container_name: home_assistant
			image: homeassistant/home-assistant:2021.2.3
			#image: homeassistant/home-assistant:2021.1.5
			restart: always
			ports:
				- "8123:8123"
			networks:
				- default
			volumes:
				- /share/CACHEDEV1_DATA/docker/home_assistant:/config 
			environment:
				- TZ=America/Los_Angeles

    Notes:

    • version & services:
      • These are used to start every Docker Compose file.
    • container_name:
      • Can be any name of your choice
    • image:
      • homeassistant/home-assistant:stable can be used in place of version number and will pull the most recent “stable” version
      • Since Home Assistant has frequent updates, I prefer to use version numbers. This gives me a chance to review & digest any breaking changes before updating
      • You can find the latest version number under releases in the main github repository
      • Also # comments out a line. Handy to keep the last version around in case you need to roll back. Infrequent, but can happen…
    • restart:
      • always means this container will always restart when docker starts
    • ports:
      • Leave these values
    • volumes:
      • Everything before :/config specifies the location on your NAS where data should be stored. Since we created a Shared Folder above you would expect that path to be /share/docker/home_assistant. But it’s not quite that simple with QNAP. You need to include CACHEDEV*x*_DATA in the path where *x* is a number. Most likely it is a 1 but it could be a 2 or even a 6 depending on how many CACHEDEV*x*_DATA folders your machine has.
      • You can SSH (see next step below) into the NAS and run df at the prompt. It shows free space, but from that you can determine how many CACHEDEV*x*_DATA folders exist on your machine. Usually it is one or no more than a few. If you are on Windows, WinSCP can be used to navigate the directory structure of your NAS to find the exact path.
    • environment:
      • TZ variable = Use this table to lookup and change the value to your local time zone

    Tips

    • Consider this example the bare minimum to get Home Assistant running on your device.
    • I also use the networks and depends_on options in my compose file, but omitted them above as they are dependent on your setup, and not needed to start Home Assistant
    • Search blog posts or github to see how others have setup their docker compose files. Here’s a sample search: google/github …pay attention to more recent dates.
    • Here’s the Docker Compose reference link again

  3. After saving the file from the last step, sign in to the NAS with a terminal program of your choice using the ssh user@IP-Address syntax at the prompt. If my NAS was located at 192.168.1.200 I would enter ssh [email protected] at the prompt.

  4. After password acceptance, enter: docker-compose -f ha_install.yml up -d at the prompt. Of course, replace ha_install.yml with your file name. This will initiate Docker Compose and you should see it proceed to pull/unpack/create the Home Assistant container. Wait for the prompt to return. If an error message was encountered double check your entries in the prior step.

  5. Home Assistant should be available a few moments after the return of the cursor. Enter the IP address of your NAS device in your browser in the form of xx.xx.xx.xx:8123. Using the example address from step 3, that would be typed as: 192.168.1.200:8123.

  6. Assuming you have Home Assistant up and running you can follow the rest of the onboarding process here.

Updating Home Assistant:

  • Manually change the version number specified in the Docker Compose file and then repeat steps 3 & 4. Docker compose will then automatically stop/pull/recreate your container.