HowTo setup HAOS - Part 0 - Architecture & Design

My aim is to start a series of posts demystifying and clearing some of the HA fog, as a lot of people find the learning curve steep. If you have deep HA development knowledge feel free to chip-in with clarifications, corrections and improvements, and most importantly let me know what I need to change to improve my content.

HA = Home Assistant

HAOS = Home Assistant Operating System (OS)

HW = Hardware

PVE = Proxmox Virtual Environment (VE)

UI = User Interface

VM = Virtual Machine

WAC = Web Admin Console (web browser GUI to administer a server - PVE, HA)

With the above out of the way let's dive into the HA architecture and design. Understanding some of the nuts and bolts might help you design better more reliable systems.

My sole focus will be HAOS. Why? Because, for most of us, I see no reason to opt for anything other than HAOS, which has it all (the Linux kernel, the GNU utilities, the HA Supervisor and the HA Core, plus all the 3rd-party apps/add-ons).

My recommendation is to install HA on PVE in an x86_x64 PC system for the ultimate, worry free experience. Why PVE? Because you can create test environments at the blink of an eye. For example, say prior to updating HA, create a replica of your production HA, make it live and experiment with the upgrade. If no issues crop up, your replica becomes you live environment. otherwise shutdown the replica and go back to your earlier production system. It literally is a matter of a few minutes to do all of this.

HAOS has been elegantly architected. For starters it uses the right tools to build a modern Linux distro with an up to date Linux kernel and all the GNU utilities required to run a modern Docker container-based Linux distro. HAOS can be installed bare-metal or in a VM. For me PVE is the ideal virtualisation environment as it offers more than any other environment and if your financial resources are limited it is zero cost; both PVE and HA. x86_x64 HW is required for PVE. An entry level x86_x64 PC has similar cost to a RPi, assuming our aim is reliability. RPi is great if your project calls for various electronics endeavours, at the cost of not being able to run HA in PVE.

From time-to-time I will use Windows lingo to describe some terms.

HA consists of the following major system components:

HA Operating System (HAOS)

the HA server is a Linux OS distro customised to meet HA requirements (provides the bare minimal Linux environment to run Supervisor and Core), hosting multiple subsystems, some of which are listed below, but can also interface with external applications, like for example Windows as well as Linux applications.

Audio System, which enables the HA Core and the Add-ons to play audio.
Command Line Interface (CLI) - the HAOS commands we can use to manage HA from the command line.
Core, the HA application which runs in a Docker container and orchestrates the integrations, interfaces, messaging & communications subsystems, plus all the other goodies HA offers. The Core interacts with the user, the supervisor and IoT devices & services (integrations).
- Integrations, which are programs designed to interface with physical devices and services, enabling an IoT infrastructure which HA leverages to deliver its magic. There are two types of integrations: built-in and community.
  - Built-in, are integrations provided by HA and can be identified by the blue/white HA image.
  - Community, are integrations developed by the community or the manufacturer of a specific device or service.

Database Management System (DBMS) - manages the HA database (read, write, delete). HA can use different DBMSs, like MariaDB or PostgreSQL, while the default is SQLite. For small installations SQLite is adequate, but for larger setups a more substantial DBMS is required.
Domain Name System (DNS), which enables the HA Core and the Add-ons to communicate with each other.
Docker, facilitates the containerised environment for the HA Core and the Add-ons to run in their own container.
- Add-ons, which are 3rd-party applications used to extend HA functionality; they run inside Docker containers. Although these add-ons can be installed as applications outside HAOS (say in a separate VM), for most users they are easier to setup while inside the HA ecosystem (HAOS).
Multicast DNS (mDNS), which auto-discovers & auto-connects physical devices & services on the network (LAN), used in Integrations to enable communication between them.
Secure Shell (SSH), a server component to allow secure remote access to HAOS, based on Dropbear SSH.
Supervisor, manages the OS, like the Network, Docker containers, which HA is using for the Core and all the Add-ons.
Webserver, which serves the Frontend, accessed by visiting the HA WAC: e.g. http://192.168.0.xxx:8123. The building blocks of the frontend are called Panels (each page in HA is a Panel). We will cover the frontend architecture in our next post.

There are more server processes running in HAOS, but are on the more technical side to cover in this guide.

HA Client

which lives outside the HAOS environment/server, includes the following clients capable of interfacing with HAOS.

Web Console, which is the primary interface we use to administer any HA installation, but can also be used as a normal control UI (with what user name you sign in, dictates if you can administer or just use HA).
Mobile Console, which is the mobile app we use to access and interface with the HA installation.
- Android app
- iOS app

Architecture schematic

A schematic depiction of what was discussed above is provided below:

From this point I shall assume you are running HA in a PVE VM. At the end of this post I provide a list of links you could refer to build a reasonable HA background, especially if you are new to this technology.

Deeper into the rabbit hole

If you are curious to check what runs under the HA hood, read on:

Visit the PVE WAC: https://192.168.0.253:8006 (your IP address will be different).

Select the VM HA is running on: 105 (HAOS) (your VMID will be different)

Select >_ Console and you should see the HA CLI waiting for you to type a command.

Type ha and press enter. You will see a list of commands you can use to interact with the HA Core.

Type core check to see what happens (you can omit the ha prefix from any command).

To see a full list of commands type help at the ha > prompt.

To see the syntax of a command type [command] -h. For example, type addons -h.

Most of the HA CLI provides commands to manage HA specific subsystems. But what if you want to go even deeper at the OS level. Enter the command login. This command will get you into the Bash shell.

Once into the Bash shell you can use any command the Bash shell supports, allowing you to interact with the Linux OS.

Type ls -al.

Type docker ps. See a list of HA docker containers running (below screenshot displays the running containers of a default HA installation).

Type systemctl list-unit-files | more. This command will show all processes available in HAOS (below screenshot displays the units of a default HA installation). The ones enabled are the ones which will be active (running) when you start HAOS. I have highlighted in red some of the more important subsystems of HAOS. Dropbear is an OpenSSH alternative used in lightweight Linux distros (sometimes called Linux appliances).

To see a list of running processes type: systemctl list-units.

systemctl is an extremely powerful command and should be used with extreme caution!

To see the command line syntax of systemctl type: systemctl -h | more.

The Bash commands available in HAOS are listed below (note commands are GNU programs and their attributes start with a - and end with an x (e.g. -rwxr-xr-x is a GNU program/utility offering a specific function). For example, docker, more, ls, which are commands used earlier, are all listed in the below screenshot.