Install on Docker – Run on Ubuntu / Debian Systems

Write for Us: Familiar with Smart Home Automation, Media Streaming, HTPC, and Home Server topics? Write for us and get paid. Writing experience not required. APPLY HERE.

In this post, I will show you how to install on Docker on Ubuntu or Debian systems. I have been running Home Assistant for my home automation needs since December of 2017, which is when I started my home automation journey. Home Assistant is a python based program for smart home automation with integration for over 1000 components. We have previously reviewed the list of best home automation controllers but none of those come close to the flexibility of Home Assistant. Unfortunately, the flexibility also means a steep learning curve for beginners.

June 28, 2020: This method is working again and I am back to using it. However, it is still not an officially supported method and could stop working anytime. I am quite confident that one of the community members will pick it up and keep it going. If you do not like the uncertainty, check my GitHub Repo for home assistant docker-compose example.

June 11, 2020: It appears that Home Assistant folks made quite a few changes over the last few months. First, there is no more The method described here would have fallen under the new "Home Assistant Supervised" name. However, the installation of Home Assistant Supervised in Docker is now an "unofficial" method and will not be supported by Home Assistant folks. Therefore, the have stopped updating removed stopped updating the HASSio install script used/linked in this post. Hopefully, a community member picks it up and keeps it updated.

There are many ways to install Home Assistant. I started out with on Raspberry Pi 3, but quickly realized it was too underpowered. Then tried Home Assistant on a Python virtual environment and finally settled on Home Assistant on Docker due to its simplicity/portability. As the title suggests, recently I decided to move from Home Assistant on Docker to on Docker on Ubuntu Server for reasons detailed below.

Home Assistant - Smart Home Hub
Home Assistant - Smart Home Hub on Raspberry Pi is the most common setup. But I wanted the benefits of (listed below), without the limitations of Raspberry Pi hardware. I decided to write this guide for people that are in my situation. [Read: What is a smart home and what can smart home automation do for you?]

Home Assistant vs

First, you may ask, I already run Home Assistant or Home Assistant on Docker. Why would I want to move to is a more self-contained home assistant setup and is much easier for beginners to install and start. Both Home Assistant and are open-source but is optimized for embedded devices like Raspberry Pi. They both offer local home automation rather than relying on cloud services.

Here are a few unique advantages of

  • Easy updates from within the web interface
  • Easy backup and restoration
  • Numerous official and community addons that extend home assistant's functionality with just few clicks. A standalone install of Home Assistant does not offer addons store. Addon Store Addon Store

While this might not sound like much to some, imagine having to maintain separate apps or docker containers for all of your home automation needs (eg. Home Assitant, MQTT Broker, NodeRed, LetsEncrypt, Dynamic DNS, and much more). Having literally spent 100s of hours on my Docker Media Server with Traefik Reverse Proxy, I can tell you that over time this can take a lot of effort. In addition, A fully qualified domain name with SSL is needed for voice assistants (eg. Google Assistant) to work with home assistant. [Read: Configure Google Assistant for Home Assistant: Paid and Free Options]

Home Assistant has a tendency to break things during updates (because it is evolving rapidly). If you don't like that, there is an addon for you on It checks if the new version is compatible with your current setup. You can then decide to upgrade or put it off for later depending on your situation. Update Checker
I Am Good To Update From Home Assistant 0.91.3 To 0.91.4

Some might argue that Home Assistant on Docker is better than on Docker and that dockerized can be quite limiting. To be clear, the limitation is not in home assistant itself but the level of management or direct tinkering that allows. If you already know Docker well, almost everything that does with addons can be replicated on any host with Docker. But do you want or have the time to do this? In my experience, the majority of users will appreciate the simplified management of all home automation apps using addons interface. It will save you a ton of time and you can focus on home automation rather than maintaining your home automation system. Furthermore, with Portainer, which is a web UI for managing docker containers (available as addon), you can manage your any addon with easy when (rarely) needed.

I Manage Both, Addons And Other Docker Apps, With Portainer
I Manage Both, Addons And Other Docker Apps, With Portainer

Still undecided? Checkout this Reddit thread to see what some of the users think.

If you are convinced, then let's move on to see how to install on Docker on Linux (Debian/Ubuntu based systems).

Build an Ultimate Raspberry Pi Smart Home Hub ~$105Price
Raspberry Pi 3 B+ Starter Kit with case, power adapter, and heat sinks~$55.00
Sandisk Ultra 16GB Micro SDHC UHS-I Card 98 MB/s~$7.50
Aeotec Z-Stick Gen5, Z-Wave Plus USB to create gateway~$45.00

Install on Docker

There are several ways to install, with Raspberry Pi setup being the most common one. But as I said before, pretty soon you will realize that Raspberry Pi is underpowered if your setup grows. Even on my AMD 5350 Ubuntu Server NAS, I found that Home Assistant was running slow. This is the main reason why I switched to a NUC for Home Automation and Docker needs.

In this guide, I will show you how to install on Docker on Linux Mint 19. But this should work on any Debian/Ubuntu systems. A little bit of commandline work is required.


First, install community edition of Docker, as described in my Docker Media Server guide. Once that is done, install other pre-requisite packages using the following command.

sudo apt-get install bash jq curl avahi-daemon dbus software-properties-common apparmor-utils

Once done, let's move on to installing on Docker.

Setup on Docker

This is the simple part, home assistant contributors have written a script to simplify setup on Docker. While almost any hardware is supported, some hardware (eg. Intel NUC, Odroid, etc.) have optimized home assistant builds. So determine your supported hardware type from the script's GitHub page.

Then run the following commands to setup on Docker on Linux:

sudo su
curl -sL | bash -s -- -m intel-nuc -d /home/user/docker/hassio

Anything after -- is optional.

  • -m intel-nuc - Replace with your machine type or remove this option.
  • -d /home/user/docker/hassio - Optional but I strongly recommend that you list a known path to store data. The path listed here is just an example.

Upon successful execution of the Docker installation script, the output should look something similar to the one below. Installation On Docker - Confirmation Message Installation On Docker - Confirmation Message

After giving a few minutes for Home Assistant to start (first time can be slow), visit the following URL:


DOCKER-HOST-IP is the local IP Address of the Linux system running Docker. You should reach Home Assistant's account creation page shown below.

Create Home Assistant Account
Create Home Assistant Account
Note that if you already had or have your previous home assistant instance running on port 8123 on your system then you will have to stop it. Otherwise, will not start due to port conflict.

You are now good to proceed with configuring, automating things, and driving people in your home nuts when something stops working.

Move Home Assistant Configuration to

What if you already had home assistant running and want to move over those configurations. Sure, you can do that. If you already have Lovelace as the Home Assistant configuration (default configuration post version 0.86) then the move is quite simple. Before proceeding stop both your previous home assistant instance and

Stopping can be tricky because supervisor will automatically start it. So you will first have to stop supervisor using the following command:

sudo systemctl stop hassio-supervisor.service

Then stop Home Assistant form the web interface Configuration->General. Then copy all the contents from Home Assistant configuration folder of your old instance to homeassistant folder within your data folder defined previously during installation.

For migrating Zwave devices, make sure zwcfg*.xml is copied as well. automatically makes any USB Zwave sticks available to home assistant, persistently. Make sure your USB device path is the same as your old setup (eg. /dev/ttyACM0). Your Z-wave devices and configurations should migrate without issues. You may want to check this thread if you have any issues with Zwave. Just make sure your previous instance is stopped.

Finally, start HASSio supervisor back up:

sudo systemctl start hassio-supervisor.service

Uninstalling on Docker

What if something goes wrong and you want to uninstall This is quite annoying because of the supervisor which keeps starting Home Assistant and its addons. Here is how I uninstalled home assistant during my testing:

First, stop supervisor.

sudo systemctl stop hassio-supervisor.service
sudo systemctl disable hassio-supervisor.service
sudo systemctl disable hassio-apparmor.service
sudo systemctl daemon-reload

Then execute the following commands:

sudo su
cd /etc/systemd/system
rm hassio-*

Now you can remove HASSio supervisor, home assistant, and addons using Portainer (if you have it running on Docker (I do) but not as an Home Assistant Addon) or using docker container rm command and the names of the containers. [Read: How to add an animated Weather Radar on Home Assistant?] on Ubuntu Server / Debian using Docker - Final Thoughts

Whether you use Home Assistant or is your call. I am liking my move from Home Assistant to on Docker. However, it certainly was not an easy move. I am pretty comfortable with Docker and Docker compose and I was cruising on my previous set up. To not able to manage containers in the way I was used to previously was a bit confusing until I learned and tweaked my methods. I also have Portainer running in a separate container and not as addon. Now, I use portainer to control and its addons, although this is rarely needed. Furthermore, this was only a problem due to my move from old Home Assistant instance to, while having both running during the transition. If you are just getting started, it will be very simple.

My setup on Intel NUC with NVMe SSD is blazing fast even with numerous components and sensors, compared to my previous setup. The community is constantly coming up with innovative addons to simplify or enhance home assistant. Therefore, if you haven't considered moving to, maybe you will consider it after reading this post. Otherwise, I hope this post helped you install on docker and harness the full power of your existing system.

Did this post help you?
SmartHomeBeginner brings in-depth tutorials easy enough to understand even for beginners. This takes considerable amount of work. If this post helps you, please consider supporting us as a token of appreciation:
  • Feeling generous? Subscribe to our content using this link (discounted options) or on Patreon. You will privileges on our Discord Server.
  • Just want to thank us? Buy us a Coffee or a Ko-Fi.
  • May be another day? Shop on Amazon using our links. Your prices won't change but we get a small commission.
  • Don't feel like spending? You can still show your support by sharing this post, linking to it in forums, or even commenting below.


Anand is a self-learned computer enthusiast, hopeless tinkerer (if it ain't broke, fix it), a part-time blogger, and a Scientist during the day. He has been blogging since 2010 on Linux, Ubuntu, Home/Media/File Servers, Smart Home Automation, and related HOW-TOs.