How to Install Home Assistant Supervised on Linux

In this article we will learn how to install Debian Linux without the GUI. We will then install a fully featured supervised installation of Home Assistant.

Note that this method will give you all of the features of Home Assistant, including the addon store.

The process is slightly more difficult than installing Home Assistant Core by itself, within a docker container.

If you have problems with this installation method, you might opt to try the Core installation by itself in order to get you started.

Install Debian Linux

If you already have a copy of Debian Linux installed, you can skip to installing Home Assistant.

First, we will install a fresh copy of the latest Debian Linux:

1. Head over the download page for the Debian Small CDs or USB sticks installer.
2. Download the correct version of Debian for your machine:
   • 64-bit Intel/AMD based machines should download the amd64 architecture.
   • 32-bit Intel/AMD based machines should download the i386 architecture.
   • 64-bit ARM based machines should download the arm64 architecture.

3. If you are building a physical machine, you will most likely need to create a bootable CD or USB stick. If you are configuring a virtual machine, you can skip this step.
   1. Download and install BalenaEtcher.
   2. Insert a USB drive (note that it will be fully erased).
   3. Open BalenaEtcher and then choose flash from file. Select the Debian installation .iso that you downloaded in step 2.
   4. Choose select target and then set the target as your USB drive.
   5. Click flash to create the Debian bootable USB.

4. Now we need to boot up our machine using the Debian installation .iso. Your machine should boot to the GNU GRUB menu.
   • If you are building a physical machine; insert the bootable USB and restart the machine.
   • If you are configuring a virtual machine, select the Debian installation .iso directly.

5. Select install to begin the installation:
   1. Set your language, location and keyboard settings as your prefer.
   2. Enter a hostname, such as homeassistant. This will be the name of your machine on your network.
   3. Domain can be left blank if you don’t have one.
   4. Enter a password for the root user.
   5. Enter a name, username and password to create a new standard user account. This is what you will use to log in, so make a note of it!
   6. Set your disk partition options. Use guided entire disk and then select the full partition.
   7. Set the partitioning scheme to all files in one partition.
   8. Choose finish partitioning and write changes to disk. You will be given one last chance to check the configuration. Choose yes to write the changes.
   9. The base system will begin installing. When prompted to scan additional installation media, choose no.
   10. Choose your country so that Debian can find the closest server for package manager. Then select an archive mirror of your preference. If in doubt, just choose deb.debian.org.
   11. If you do not use a HTTP proxy, or if in doubt, leave the HTTP proxy blank and click continue.
   12. Choose whether you want to partake in the popularity contest. If in doubt, just choose no.
   13. When presented with the software selection, ensure that only the following components are installed:
       • SSH Server
       • standard system utilities
   14. When you get to the installation complete screen, remove the USB stick or installation media, then click continue to reboot.
   15. Once your machine boots to the Debian login prompt, go ahead a log in with the credentials you created during installation.
       
       Note that we did not install the GUI, as it is not required for Home Assistant.

Installing Home Assistant Supervised on Debian

At this stage you should have a working virtual machine running Debian command line. The next step is to install Home Assistant.

For the first few tasks we need to be logged in as root, which we can do with the following command.

su -

You will need to enter the credentials that you chose during installation.

Backup network settings

After attempting this build several times prior to writing this article, I found that installing Home Assistant caused problems with the network configuration.

Therefore the first I would recommend doing is to backup the network configuration settings file using the following command.

cp /etc/network/interfaces /etc/network/interfaces.bak

Home Assistant Supervised Installation

We will be using the Home Assistant supervised installer, which is found over on GitHub. I have linked it in case you need to reference it for any reason.

Install Dependencies

First go ahead and install the dependencies with the following command.

apt-get install \
jq \
wget \
curl \
udisks2 \
libglib2.0-bin \
network-manager \
systemd-journal-remote \
dbus -y

Install Docker-CE

Next we will install Docker-CE with the following command.

curl -fsSL get.docker.com | sh

Install OS-Agent

We also need to install OS-Agent from GitHub releases. Go ahead and visit the releases download page.

There are quite a few packages available, you need to choose the correct one for your build. If you are building on Debian arm64 (for M1 Mac) then you should choose the _aarch64.deb package.

The easiest way to get it via the Debian command line is with wget. Right-click the package and copy the link address, then use this address with the wget command.

wget <OS-agent URL>

For example, at the time of writing the current version is 1.2.2, therefore the command would be as follows.

wget https://github.com/home-assistant/os-agent/releases/download/1.2.2/os-agent_1.2.2_linux_aarch64.deb

Once the package has downloaded, we can install it with dpkg followed by the package name.

sudo dpkg -i os-agent_1.2.2_linux_aarch64.deb

Once complete, you can test the installation with the following command.

gdbus introspect --system --dest io.hass.os --object-path /io/hass/os

This command should not produce and error. The output should look something like the following.

Home Assistant Supervised Debian Package Installation

The last thing remaining to do is install Home Assistant. This can be done with the Home Assistant supervised debian package.

First we can go ahead and download the package using wget.

wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb

Once the download has completed, we can install it with dpkg.

dpkg -i homeassistant-supervised.deb

You may need to select a machine type. For M1 Mac builds running Debian arm64, choose qemuarm-64.

Once the installation has completed, Home Assistant will start up but it will take a few minutes before we can access it.

The IP address of our Home Assistant server is given at the end of installation, in my case 192.168.64.5:8123.

In order to check that the installation was successful, go ahead and visit the IP address using a browser.

http://<your-ip-address>:<your-port>

So in my case it would be as follows.

http://192.168.64.5:8123

If you get the onboarding screen, awesome!

However we should also check that the server can withstand a reboot. This caused me several problems on previous attempts to get this to work.

Go ahead and reboot the server with the following command.

reboot now

Fixing Network Interface Problems

At the time of writing, when the server is rebooted I find that it no longer has a working network connection. You can check this by logging in and attempting to ping Google.

ping google.com

If you receive a name resolution error, it means that the network settings have been corrupted by the Home Assistant installation.

The problem seems to be that /etc/network/interfaces gets overwritten in the Home Assistant installation process.

However this is very easy to fix using the backup that we created earlier. First log back into the superuser account following the reboot.

su -

Next we will restore the /etc/network/interfaces file which we made a backup of earlier.

mv -f /etc/network/interfaces.bak /etc/network/interfaces

Once we have restored our backup, we can reboot the system.

reboot now

After reboot, everything should be back to normal! You should once again be able to access your Home Assistant server in your web browser.

Whats’ Next?

If you have got this this stage, congratulations! Hopefully you now have Debian and Home Assistant up and running.

If you are new to Home Assistant, the next step is to check out the YAML beginners guide.

If you have some Home Assistant experience, why not go ahead and check out some of my other Home Assistant tutorials!