Alternative


Install Home Assistant Operating System

Follow this guide if you want to get started with Home Assistant easily or if you have little to no Linux experience

Download the appropriate image

Create the Virtual Machine

Load the appliance image into your virtual machine software. (Note: You are free to assign as much resources as you wish to the VM, please assign enough based on your add-on needs)

Minimum recommended assignments:

  • 2GB RAM
  • 32GB Storage
  • 2vCPU

All these can be extended if your usage calls for more resources.

Hypervisor specific configuration

  1. Create a new virtual machine
  2. Select “Other Linux (64Bit)
  3. Select “Use an existing virtual hard disk file”, select the VDI file from above
  4. Edit the “Settings” of the VM and go “System” then Motherboard and Enable EFI
  5. Then “Network” “Adapter 1” Bridged and your adapter.
  1. Create a new virtual machine in virt-manager
  2. Select “Import existing disk image”, provide the path to the QCOW2 image above
  3. Choose “Generic Default” for the operating system
  4. Check the box for “Customize configuration before install”
  5. Select your bridge under “Network Selection”
  6. Under customization select “Overview” -> “Firmware” -> “UEFI x86_64: …”.****

Use the “E1001” or “E1001E” virtual network adapater. There are confirmed mDNS/Multicast discovery issues when using VMware’s “VMXnet3” virtual network adapter.

Start up your Virtual Machine

  1. Start the Virtual Machine
  2. Observe the boot process of Home Assistant Operating System
  3. Once completed you will be able to reach Home Assistant on homeassistant.local:8123. If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at homeassistant:8123 or http://X.X.X.X:8123 (replace X.X.X.X with your ’s IP address).

With the Home Assistant Operating System installed and accessible you can continue with onboarding.

Onboarding

Install Home Assistant Container

Synology NAS

As Synology within DSM now supports Docker (with a neat UI), you can simply install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see https://www.synology.com/en-us/dsm/packages/Docker

The steps would be:

  • Install “Docker” package on your Synology NAS
  • Launch Docker-app and move to “Registry”-section
  • Find “homeassistant/home-assistant” within registry and click on “Download”. Choose the “stable” tag.
  • Wait for some time until your NAS has pulled the image
  • Move to the “Image”-section of the Docker-app
  • Click on “Launch”
  • Choose a container-name you want (e.g., “homeassistant”)
  • Click on “Advanced Settings”
  • Set “Enable auto-restart” if you like
  • Within “Volume” click on “Add Folder” and choose either an existing folder or add a new folder. The “mount path” has to be “/config”, so that Home Assistant will use it for the configs and logs. It is therefore recommended that the folder you choose should be named “config” or “homeassistant/config” to avoid confusion when referencing it within service calls.
  • Within “Network” select “Use same network as Docker Host”
  • To ensure that Home Assistant displays the correct timezone go to the “Environment” tab and click the plus sign then add variable = TZ & value = Europe/London choosing your correct timezone
  • Confirm the “Advanced Settings”
  • Click on “Next” and then “Apply”
  • Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example http://192.168.1.10:8123)

If you are using the built-in firewall, you must also add the port 8123 to allowed list. This can be found in “Control Panel -> Security” and then the Firewall tab. Click “Edit Rules” besides the Firewall Profile dropdown box. Create a new rule and select “Custom” for Ports and add 8123. Edit Source IP if you like or leave it at default “All”. Action should stay at “Allow”.

To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal acces to your Synology NAS:

https://www.synology.com/en-global/knowledgebase/DSM/help/DSM/AdminCenter/system_terminal

Adjust the following Terminal command as follows :

  • Replace /PATH_TO_YOUR_CONFIG points at the folder where you want to store your configuration
  • Replace /PATH_TO_YOUR_USB_STICK matches the path for your USB stick (e.g., /dev/ttyACM0 for most Synology users)
  • Replace “Australia/Melbourne” with your timezone

Run it in Terminal.

sudo docker run --restart always -d --name homeassistant -v /PATH_TO_YOUR_CONFIG:/config --device=/PATH_TO_YOUR_USB_STICK -e TZ=Australia/Melbourne --net=host homeassistant/home-assistant:stable

Complete the remainder of the Z-Wave configuration by following the instructions here.

Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following:

  • Go to the Docker-app and move to “Registry”-section
  • Find “homeassistant/home-assistant” within registry and click on “Download”. Choose the “stable” tag.
  • Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar)
  • Move to “Container”-section
  • Stop your container if it’s running
  • Right-click on it and select “Action”->“Clear”. You won’t lose any data, as all files are stored in your configuration-directory
  • Start the container again - it will then boot up with the new Home Assistant image

Remark: to restart your Home Assistant within Synology NAS, you just have to do the following:

  • Go to the Docker-app and move to “Container”-section
  • Right-click on it and select “Action”->“Restart”.

If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assistant on Synology Docker these instructions do not correctly configure the container to access the USB devices. To configure these devices on your Synology Docker Home Assistant you can follow the instructions provided here by Phil Hawthorne.

QNAP NAS

As QNAP within QTS now supports Docker (with a neat UI), you can simply install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see https://www.qnap.com/solution/container_station/en/index.php

The steps would be:

  • Install “Container Station” package on your Qnap NAS
  • Launch Container Station and move to “Create Container”-section
  • Search image “homeassistant/home-assistant” with Docker Hub and click on “Install” Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is “homeassistant/armhf-homeassistant”
  • Choose “stable” version and click next
  • Choose a container-name you want (e.g., “homeassistant”)
  • Click on “Advanced Settings”
  • Within “Shared Folders” click on “Volume from host” > “Add” and choose either an existing folder or add a new folder. The “mount point has to be /config, so that Home Assistant will use it for the configuration and logs.
  • Within “Network” and select Network Mode to “Host”
  • To ensure that Home Assistant displays the correct timezone go to the “Environment” tab and click the plus sign then add variable = TZ & value = Europe/London choosing your correct timezone
  • Click on “Create”
  • Wait for some time until your NAS has created the container
  • Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example http://192.xxx.xxx.xxx:8123)

Remark: To update your Home Assistant on your Docker within Qnap NAS, you just remove container and image and do steps again (Don’t remove “config” folder).

If you want to use a USB Bluetooth adapter or Z-Wave USB stick with Home Assistant on Qnap Docker, follow those steps:

Z-Wave

  • Connect to your NAS over SSH

  • Load cdc-acm kernel module(when NAS restart need to run this command) insmod /usr/local/modules/cdc-acm.ko

  • Find USB devices attached. Type command: 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. Like : ttyACM0

  • Run Docker command:

    docker run --init --name homeassistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e TZ=Europe/London --device /dev/ttyACM0 homeassistant/home-assistant:stable
    

    -v is your configuration path -e is set timezone

  • Edit configuration.yaml

zwave:
  usb_path: /dev/ttyACM0

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

Bluetooth

  • Connect to your NAS over SSH

  • Run Docker command:

    docker run --init --name homeassistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e TZ=Europe/London -v /dev/bus/usb:/dev/bus/usb -v /var/run/dbus:/var/run/dbus homeassistant/home-assistant:stable
    

    First -v is your configuration path -e is set timezone

  • Edit the configuration.yaml file

device_tracker:
  - platform: bluetooth_tracker

Once the Home Assistant Container is running Home Assistant should be accessible using http://<host>:8123 (replace with the hostname or IP of the system). You can continue with onboarding.

Onboarding

Restart Home Assistant

If you change the configuration you have to restart the server. To do that you have 3 options.

  1. In your Home Assistant UI go to the Configuration panel -> Server management and click the “Restart” button.
  2. You can go to the Developer Tools -> Services, select the service homeassistant.restart and click “Call Service”.
  3. Restart it from a terminal.
docker restart homeassistant
docker-compose restart

Docker Compose

As the Docker command becomes more complex, switching to docker-compose can be preferable and support automatically restarting on failure or system restart. Create a docker-compose.yml file:

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: homeassistant/home-assistant:stable
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    network_mode: host

Start it by running:

docker-compose up -d

Exposing Devices

In order to use Z-Wave, Zigbee or other integrations that require access to devices, you need to map the appropriate device into the container. Ensure the user that is running the container has the correct privileges to access the /dev/tty* file, then add the device mapping to your container instructions:

docker run ... --device /dev/ttyUSB0:/dev/ttyUSB0 ...
version: '3'
services:
  homeassistant:
    ...
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

Optimizations

The Home Assistant Container is using an alternative memory allocation library jemalloc for better memory management and Python runtime speedup.

As jemalloc can cause issues on certain hardware, it can be disabled by passing the environment variable DISABLE_JEMALLOC with any value, for example:

docker run ... -e "DISABLE_JEMALLOC=true" ...
version: '3'
services:
  homeassistant:
  ...
  environment:
    DISABLE_JEMALLOC: true

The error message <jemalloc>: Unsupported system page size is one known indicator.

Community provided guides

Additional installation guides can be found on our Community Forum.

These Community Guides are provided as-is. Some of these install methods are more limited than the methods above. Some integrations may not work due to limitations of the platform.