This guide will go over how to install Home Assistant (Supervised) on Debian based Linux Distributions. I have modified this Guide to be Debian since Ubuntu Server is no longer officially supported

Important Please Read

Before continuing make sure you read and understand the following documents:

0014. Installation method: Home Assistant Supervised

0012. Define supported installation method

Pre-installation Steps

Step 1: Becoming Root

Before we start, you must make sure you are logged in as root, Debian may not come with sudo installed, so in order to become root type:

su -

Then enter the root password you configured during installation, Be sure not to forget the dash as it allows the system to run the login scripts for the root user.

However, if you are on a system with sudo installed you can use the command:

sudo su -

Before preceding, confirm you are root by typing:

whoami

You must be root in order to continue

Step 2: Updating your System

Before starting it is a good idea to update your system, to do so enter the three following commands:

apt-get update
apt-get upgrade -y
apt-get dist-upgrade -y

Step 3: Install Dependency’s

Install all the required dependency’s with the following command:

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

Step 1: Install The Docker Engine

1. Run the Docker CE installation script

Simply run the Docker CE for Linux installation script:

curl -fsSL get.docker.com | sh

2. Test your Docker Install (Optional)

To test your docker install run the hello-world script:

docker run hello-world

If Docker is working correctly the following message will be displayed:

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Step 2: Install Home Assistant

Installing Home Assistant is easy simply follow these steps

1. Install the OS Agent

The OS Agent allows the Home Assistant Supervisor to communicate with D-Bus and will soon be required

To Install it simply use the follow commands:

wget https://github.com/home-assistant/os-agent/releases/latest/download/os-agent_1.2.2_linux_x86_64.deb
dpkg -i os-agent_1.2.2_linux_x86_64.deb

Of course being sure you replace `os-agent_1.2.2_linux_x86_64.deb` with the latest version which matches your CPU architecture. Available at the GitHub Releases page

2. Run the Home Assistant Install Script

Now that you are root simply run these commands to download and install Home Assistant Supervised:

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

After it has finished running you should be able to access Home Assistant from:

http://your.ip.address.here:8123

Step 3: Post Install Steps

1. Install The SSH Add On

The SSH add on in Home Assistant allows you to access the Home Assistant command line interface which can be vary helpful for diagnosing issues with you Home Assistant install

  • To install SSH head to the Supervisor tab
  • Then click Add on Store
  • Now find Terminal & SSH and Click install

Before starting you must set a password and change the port as port 22 is already used by the Host’s SSH server

So before you start the Addon head to the configuration tab and change the Port setting under Network and add a password. Be sure to save both these settings then you can start the add on

You should now be able to now SSH into your hassio instance using the command

ssh [email protected] -p 29

2. Install SAMBA

SAMBA will allow you to access your configuration files from any PC on your local network

To install it simply

Find SAMBA share in the add on store

Edit the Configuration to to include your own username and password

Then save the config and start the add on

Now you should be able to access your files from any file manager on the network by typing

\\your.ip.address.here\

into your file browser

Your Home Assistant config files will be found in the config folder

Congratulations you have now setup Home Assistant!!!

Thanks for reading, if you have any questions feel free to contact me on Twitter or the DrZzs Discord Server

Notes:

Ubuntu Server is no longer officially supported by Home Assistant

Home Assistant (Supervised) now only officially supports the latest version of Debian, That means that if anything breaks you cannot complain about it. However they are not preventing you from still installing it If you are installing Home Assistant Supervised on anything other than Debian Bullseye you will get this notice in your supervisor (as shown in the image below):

To learn more please read the Home Architecture Decision Record Documents:

0014. Installation method: Home Assistant Supervised

0012. Define supported installation method

Also be sure to update me in the comments below or reach out to me on Twitter or Discord if you run into any issues you believe to be caused by this change

35 Replies to “Install Home Assistant (Supervised) on Debian”

  1. My Bad. This IS working. I just needed to change a few things to accommodate running Ubuntu Server 20.4 on a RPi 4 8GB. All good now. Thanks for your write-up! It helped quite a bit.

  2. I constantly had issues (data corruption, reboot failures etc.) with HassOS running in Oracle VirtualBox under Windows 10. I decided to try Debian and Portainer and it seems to be running stable so far. Thanks for the tips!

  3. If you are installing under Debian, Ubutnu or other system, you may(will) find that you lose audio when you install Home Assistant. For example, if you want to run Zoom on the same system…or play music outside Home Assistant. Everything looks right, you just can’t hear anything 🙂

    Home Assistant grabs the system audio as part of it’s startup….just in case you might want to use it. There is no option in Home Assistant to stop this….but the solution can be found at: https://community.home-assistant.io/t/audio-not-working-after-installing-hass-io-in-docker/178858/5 .

  4. I’m getting errors on the last step trying to run dpkg -i homeassistant-supervised.deb. it tells me that there is a dpkg divert error rename involves overwriting NetworkManager.conf to NetworkManager.conf.real and is not allowed.

  5. Sorry to double post, the actual error message is:
    [email protected]:/home/pi# dpkg -i homeassistant-supervised.deb
    (Reading database … 100099 files and directories currently installed.)
    Preparing to unpack homeassistant-supervised.deb …
    [warn]
    [warn] If you want more control over your own system, run
    [warn] Home Assistant as a VM or run Home Assistant Core
    [warn] via a Docker container.
    [warn]
    [warn] ModemManager service is enabled. This might cause issue when using serial devices.
    Leaving ‘diversion of /etc/NetworkManager/NetworkManager.conf to /etc/NetworkManager/NetworkManager.conf.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/NetworkManager/system-connections/default to /etc/NetworkManager/system-connections/default.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/docker/daemon.json to /etc/docker/daemon.json.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/network/interfaces to /etc/network/interfaces.real by homeassistant-supervised’
    Unpacking homeassistant-supervised (1.0.0) over (1.0.0) …
    Removing ‘diversion of /etc/NetworkManager/NetworkManager.conf to /etc/NetworkManager/NetworkManager.conf.real by homeassistant-supervised’
    dpkg-divert: error: rename involves overwriting ‘/etc/NetworkManager/NetworkManager.conf’ with
    different file ‘/etc/NetworkManager/NetworkManager.conf.real’, not allowed
    dpkg: warning: old homeassistant-supervised package post-removal script subprocess returned error exit status 2
    dpkg: trying script from the new package instead …
    Removing ‘diversion of /etc/NetworkManager/NetworkManager.conf to /etc/NetworkManager/NetworkManager.conf.real by homeassistant-supervised’
    dpkg-divert: error: rename involves overwriting ‘/etc/NetworkManager/NetworkManager.conf’ with
    different file ‘/etc/NetworkManager/NetworkManager.conf.real’, not allowed
    dpkg: error processing archive homeassistant-supervised.deb (–install):
    new homeassistant-supervised package post-removal script subprocess returned error exit status 2
    [warn]
    [warn] If you want more control over your own system, run
    [warn] Home Assistant as a VM or run Home Assistant Core
    [warn] via a Docker container.
    [warn]
    [warn] ModemManager service is enabled. This might cause issue when using serial devices.
    Leaving ‘diversion of /etc/NetworkManager/NetworkManager.conf to /etc/NetworkManager/NetworkManager.conf.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/NetworkManager/system-connections/default to /etc/NetworkManager/system-connections/default.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/docker/daemon.json to /etc/docker/daemon.json.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/network/interfaces to /etc/network/interfaces.real by homeassistant-supervised’
    Removing ‘diversion of /etc/NetworkManager/NetworkManager.conf to /etc/NetworkManager/NetworkManager.conf.real by homeassistant-supervised’
    dpkg-divert: error: rename involves overwriting ‘/etc/NetworkManager/NetworkManager.conf’ with
    different file ‘/etc/NetworkManager/NetworkManager.conf.real’, not allowed
    dpkg: error while cleaning up:
    new homeassistant-supervised package post-removal script subprocess returned error exit status 2
    Errors were encountered while processing:
    homeassistant-supervised.deb
    [email protected]:/home/pi#

  6. Hi, I am getting the same errors as above:

    “`
    (Reading database … 22530 files and directories currently installed.)
    Preparing to unpack homeassistant-supervised.deb …
    [warn]
    [warn] If you want more control over your own system, run
    [warn] Home Assistant as a VM or run Home Assistant Core
    [warn] via a Docker container.
    [warn]
    [warn] ModemManager service is enabled. This might cause issue when using serial devices.
    [info] Fix kernel dmesg restriction
    /var/lib/dpkg/tmp.ci/preinst: line 21: /proc/sys/kernel/dmesg_restrict: Read-only file system
    dpkg: error processing archive homeassistant-supervised.deb (–install):
    new homeassistant-supervised package pre-installation script subprocess returned error exit status 1
    [info] Undo divert on abort-install
    No diversion ‘diversion of /etc/NetworkManager/NetworkManager.conf to /etc/NetworkManager/NetworkManager.conf.real by homeassistant-supervised’, none removed.
    No diversion ‘diversion of /etc/NetworkManager/system-connections/default to /etc/NetworkManager/system-connections/default.real by homeassistant-supervised’, none removed.
    No diversion ‘diversion of /etc/docker/daemon.json to /etc/docker/daemon.json.real by homeassistant-supervised’, none removed.
    No diversion ‘diversion of /etc/network/interfaces to /etc/network/interfaces.real by homeassistant-supervised’, none removed.
    Errors were encountered while processing:
    homeassistant-supervised.deb
    “`

    Setup within a Debian 11 Proxmox Container.
    Nesting is true
    and it is an unprivileged container

  7. Hi, any chance to have aarch64 in the menu? Or what have I choice for s905x3 4/64? It works as rpi4 64, but not sure if this is correct.

  8. It is asking for the machine type in the menu. And after that I have homeassistant container of a chosen type. And others aarch64. At the moment after fresh install I have::

    ghcr.io/home-assistant/aarch64-hassio-multicast:2021.04.0
    ghcr.io/home-assistant/aarch64-hassio-audio:2021.07.0
    ghcr.io/home-assistant/aarch64-hassio-dns:2021.06.0
    ghcr.io/home-assistant/aarch64-hassio-cli:2021.09.0
    ghcr.io/home-assistant/odroid-n2-homeassistant:2021.10.6
    ghcr.io/home-assistant/aarch64-hassio-observer:2021.10.0
    homeassistant/aarch64-hassio-supervisor
    portainer/portainer-ce

    Pi 4, odroids, and qemu arm, are booting, hove ever I did not find what are the differences of this images, and which is better (think aarch64 like others) in my case.

  9. Thanks for this guide. I’ve run in to some issues:
    1) Curl wasn’t installed by default, so had to install that (before installing Docker).
    2) Docker wouldn’t start because of some IP tables, but an easy fix: https://github.com/microsoft/WSL/discussions/4872
    3) When loading the pre-requisites, noticed that avahi-daemon had some failures, but not sure if that’s relevant:
    Setting up avahi-daemon (0.8-5) …
    invoke-rc.d: could not determine current runlevel
    Reloading system message bus config…Failed to open connection to “system” message bus: Failed to connect to socket /run/dbus/system_bus_socket: No such file or directory
    invoke-rc.d: initscript dbus, action “force-reload” failed.
    invoke-rc.d: could not determine current runlevel
    Created symlink /etc/systemd/system/dbus-org.freedesktop.Avahi.service -> /lib/systemd/system/avahi-daemon.service.
    Created symlink /etc/systemd/system/multi-user.target.wants/avahi-daemon.service -> /lib/systemd/system/avahi-daemon.service.

    4) the real problem is that I can’t get OS-Agent to install properly:
    [email protected]:~# dpkg -i os-agent_1.2.2_linux_x86_64.deb
    Selecting previously unselected package os-agent.
    (Reading database … 13275 files and directories currently installed.)
    Preparing to unpack os-agent_1.2.2_linux_x86_64.deb …
    Unpacking os-agent (1.2.2) …
    Setting up os-agent (1.2.2) …
    System has not been booted with systemd as init system (PID 1). Can’t operate.
    Failed to connect to bus: Host is down
    Created symlink /etc/systemd/system/multi-user.target.wants/haos-agent.service -> /usr/lib/systemd/system/haos-agent.service.
    System has not been booted with systemd as init system (PID 1). Can’t operate.
    Failed to connect to bus: Host is down
    dpkg: error processing package os-agent (–install):
    installed os-agent package post-installation script subprocess returned error exit status 1
    Processing triggers for dbus (1.12.20-2) …
    Errors were encountered while processing:
    os-agent

    Docker is running, but when I try to install os-agent again, I get:
    [email protected]:~# dpkg -i os-agent_1.2.2_linux_x86_64.deb
    (Reading database … 13279 files and directories currently installed.)
    Preparing to unpack os-agent_1.2.2_linux_x86_64.deb …
    System has not been booted with systemd as init system (PID 1). Can’t operate.
    Failed to connect to bus: Host is down
    Removed /etc/systemd/system/multi-user.target.wants/haos-agent.service.
    Unpacking os-agent (1.2.2) over (1.2.2) …
    System has not been booted with systemd as init system (PID 1). Can’t operate.
    Failed to connect to bus: Host is down

    ANY [email protected]:~# dpkg -i os-agent_1.2.2_linux_x86_64.deb
    (Reading database … 13279 files and directories currently installed.)
    Preparing to unpack os-agent_1.2.2_linux_x86_64.deb …
    System has not been booted with systemd as init system (PID 1). Can’t operate.
    Failed to connect to bus: Host is down
    Removed /etc/systemd/system/multi-user.target.wants/haos-agent.service.
    Unpacking os-agent (1.2.2) over (1.2.2) …
    System has not been booted with systemd as init system (PID 1). Can’t operate.
    Failed to connect to bus: Host is down

    Any ideas?

  10. Actually, solved the issue with systemd by installing Genie.

    But then my network connection stopped working. I successfully installed OS handler and HA but then the script stopped because HA couldn’t reach a network.

    Anyone have this issue (either docker or genie killing network connection)? I’ve restarted-no dice.

  11. Just going through your document to install on Bullseye. One thought on your documentation:
    In Step 1 you install docker with a curl command.
    In Step 2 you install dependencies one of which is curl.
    Maybe you should have those reversed. Don’t think any of the dependencies require docker do they?

  12. I got the same error message by sudo dpkg -i homeassistant-supervised.deb

    ————————————————
    sudo dpkg -i homeassistant-supervised.deb
    (Reading database … 171539 files and directories currently installed.)
    Preparing to unpack homeassistant-supervised.deb …
    [warn]
    [warn] If you want more control over your own system, run
    [warn] Home Assistant as a VM or run Home Assistant Core
    [warn] via a Docker container.
    [warn]
    Leaving ‘diversion of /etc/NetworkManager/NetworkManager.conf to /etc/NetworkManager/NetworkManager.conf.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/NetworkManager/system-connections/default to /etc/NetworkManager/system-connections/default.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/docker/daemon.json to /etc/docker/daemon.json.real by homeassistant-supervised’
    Leaving ‘diversion of /etc/network/interfaces to /etc/network/interfaces.real by homeassistant-supervised’
    Unpacking homeassistant-supervised (1.0.2) over (1.0.2) …
    dpkg: dependency problems prevent configuration of homeassistant-supervised:
    homeassistant-supervised depends on network-manager; however:
    Package network-manager is not installed.
    homeassistant-supervised depends on jq; however:
    Package jq is not installed.

    dpkg: error processing package homeassistant-supervised (–install):
    dependency problems – leaving unconfigured
    Errors were encountered while processing:
    homeassistant-supervised

    ———————————————————-

    any issue to fix it?

    thanks for your help

  13. I am getting error in the last stage.

    Portainer log shows
    Can’t install ghcr.io/home-assistant /None-homeassistant:landingpage: 400 Client Error for http+dicker://localhost/v1.41/images/create?tag=landingpage

  14. Hi! I did everything listed and at the end was presented with this after entering
    dpkg -i os-agent_1.2.2_linux_x86_64.deb

    — version.home-assistant.io ping statistics —
    1 packets transmitted, 1 received, 0% packet loss, time 0ms
    rtt min/avg/max/mdev = 9.234/9.234/9.234/0.000 ms
    [info] Install supervisor Docker container
    [info] Install supervisor startup scripts
    [info] Install AppArmor scripts
    [info] Start Home Assistant Supervised
    [info] Installing the ‘ha’ cli

    and home assistant didn’t install. I am not sure what to do. If it matters my system is a HP Chromebox 1.4 GHz Celeron chip with 4 GB of ram and 16 GB SSD running obviously Debian 11. Please be kind since I’m new at Linux and Home Assistant 🙂

  15. [email protected]:~# docker ps
    CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
    f73df3bd0f22 ghcr.io/home-assistant/amd64-hassio-multicast:2021.04.0 “/init” 2 minutes ago Up 2 minutes hassio_multicast
    b55409d5a6f6 ghcr.io/home-assistant/amd64-hassio-audio:2021.07.0 “/init” 2 minutes ago Up 2 minutes hassio_audio
    2e0880adf56d ghcr.io/home-assistant/amd64-hassio-dns:2021.06.0 “/init” 2 minutes ago Up 2 minutes hassio_dns
    0c2290496e61 ghcr.io/home-assistant/amd64-hassio-cli:2021.09.0 “/init /bin/bash -c …” 2 minutes ago Up 2 minutes hassio_cli
    5f45d8786007 ghcr.io/home-assistant/amd64-hassio-observer:2021.10.0 “/init” About an hour ago Up 2 minutes 0.0.0.0:4357->80/tcp, :::4357->80/tcp hassio_observer
    f66b029b9a29 homeassistant/amd64-hassio-supervisor “/init” About an hour ago Up 2 minutes hassio_supervisor

    this is what comes up after putting in “docker ps”

    1. It looks to be alive for everything but the home assistant core, the easiest fix IMO would be to reboot the host then wait two minutes after boot and run `ha su logs` to see what is going on

  16. I did that and the only warning thrown out was this

    21-11-23 23:49:49 WARNING (MainThread) [supervisor.dbus.manager] Can’t load dbus interface de.pengutronix.rauc: The name de.pengutronix.rauc was not provided by any .service files

    the rest were green.

  17. Hi Matheson,
    I don’t find how to change the folder data “/usr/share/hassio” that is inaccessible on my omv to another “/srv/dev-disk-by-uuid-#####/hassio when i install home assistant supervised

Leave a Reply

Your email address will not be published. Required fields are marked *