Home Assistant in a FreeBSD jail Link to heading

Home Assistant is one of the services that I rely on heavily. I use it to keep track of temperature, control heaters and fans, and run timers. In the past I have run it in virtual machines and docker containers, but now that I am moving across to FreeBSD as my server of choice, I want to get it running in a jail. I know that I can run the HAOS VM in bhyve and pass through a USB controller, but I’d like to run the service without the overhead of a virtual machine.

Software installed Link to heading

This has been tested and is working as of 10 December 2023

• Python 3.11
• Home Assistant 2023.12.1
• FreeBSD 14.0 jail

Poudriere Link to heading

To get this working, I used packages compiled with poudriere. I used poudriere to set the default version of Python to 3.11 because this required by Home Assistant. The default version of python in the FreeBSD repository is 3.9. I won’t explain how to set up and use poudriere because the Insane.Engineer, Vermaden, and Benedict Reuschling have covered this in great depth. What I will describe is what I needed to customise.

Step 1: Set 3.11 as the default version of python:

poudriere jail # vim /usr/local/etc/poudriere.d/python311-make.conf 

DEFAULT_VERSIONS+= python=3.11 python3=3.11

Step 2: Make a list of packages for poudriere to compile:

poudriere jail # cat /usr/local/etc/poudriere.d/list-py311

databases/py-sqlite3
devel/cmake
devel/git
devel/gmake
editors/vim
graphics/libjpeg-turbo
graphics/py-pillow
lang/gcc
lang/rust
math/py-numpy
multimedia/ffmpeg
shells/bash
www/npm

(Note: devel/gmake, lang/gcc, and www/npm aren’t necessary for Home Assistant, but I will use them later to install Zigbee2MQTT. Also: editors/vim is just my personal preference)

Step 3: Tells poudriere to create the packages listed in list-py311 using the customised python311-make.conf.

poudriere jail # poudriere bulk -j 140Ramd64 -f /usr/local/etc/poudriere.d/list-py311 -z python311

Overall Link to heading

Ideally, we should be able to get Home Assistant up and running by:

1. Installing needed software
   • bash
   • ffmpeg
   • openblas
   • py311-sqlite
   • rust
2. Creating a dedicated user
3. Creating a python virtual environment
4. Install HA into the virtual environment
   • This pulls in software needed to install HA
5. Run HA
   • This pulls in software needed to run HA

These steps are based on guides written by Dan Langille and Engr. Rez Cab.

However, as of 10 December 2023, we need to manually install a few of the dependencies that fail to install properly on FreeBSD. This effectively creates a Step 3a.

Step 1: Setting up the jail Link to heading

Install the following packages:

home assistant jail # pkg install bash cmake ffmpeg git openblas pkgconf py311-pillow py311-sqlite3 rust

Git was not required for HA but was required in Step 3a. Similarly, py311-pillow was installed manually because it fails to install during the initial run of hass - see here

Step 2: Setting up the dedicated user Link to heading

Set up a user for home assistant:

home assistant jail # pw useradd homeassistant -w no -m -c "Home Assistant"

home assistant jail # pw groupmod dialer -m homeassistant

home assistant jail # chmod 770 /home/homeassistant

home assistant jail # pw usermod homeassistant -s /usr/local/bin/bash

Switch to the newly created homeassistant user to continue the installation:

home assistant jail # su - homeassistant

Step 3: Setting up the virtual environment Link to heading

Before you set up the virtual environment, take note of the user’s $PATH:

home assistant jail $ echo $PATH
/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/home/homeassistant/bin

Run the following commands to set up a python virtual environment in a newly created home-assistant folder:

home assistant jail $ mkdir home-assistant

home assistant jail $ cd home-assistant/

home assistant jail ~/home-assistant $ python3.11 -m venv .

home assistant jail ~/home-assistant $ source bin/activate

(home-assistant) home assistant jail ~/home-assistant $

Now, when you look at the user’s $PATH you can see that the new python virtual environment has been loaded and it points to new executables:

(home-assistant) home assistant jail $ echo $PATH
/usr/home/homeassistant/home-assistant/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/home/homeassistant/bin

(home-assistant) home assistant jail $ which pip
/usr/home/homeassistant/home-assistant/bin/pip

(home-assistant) home assistant jail ~/home-assistant $ which python
/usr/home/homeassistant/home-assistant/bin/python

Upgrade pip and install wheel, the python package manager:

(home-assistant) home assistant jail ~/home-assistant $ pip install --upgrade pip

(home-assistant) home assistant jail ~/home-assistant $ pip install wheel

Step 3a: Manually installed dependencies Link to heading

This is the section that will change over time as Home-Assistant’s dependencies are updated. Writing up this section was a process of trial-and-error. I would start the installation process and then look to see what failed.

Each failure occurred during Steps 4 or 5 when dependencies were being pulled in as part of the installation processes. Thankfully, each of these failures were due to dependencies that needed to be patched in order to install on FreeBSD.

python-zlib-ng Link to heading

(Confirmed 2023-12-10)

We need to use a patched fork of python-zlib-ng because the currently available python-zlib-ng (version 0.2.0) does not build on FreeBSD.

(home-assistant) home assistant jail ~/home-assistant $ pip install git+https://github.com/LukaszMoskala/python-zlib-ng.git

Note: this is planned to be fixed in the future.

webrtc-noise-gain Link to heading

(Confirmed 2023-12-10)

Version 1.2.3 of webrtc-noise-gain does not build on FreeBSD. Some patches have been submitted after version 1.2.3 was released.

(home-assistant) home assistant jail ~/home-assistant $ pip install git+https://github.com/rhasspy/webrtc-noise-gain.git

This is a known issue.

numpy Link to heading

(Confirmed 2023-12-10)

You need to install numpy manually from the instructions here

(home-assistant) home assistant jail $ git clone https://github.com/numpy/numpy.git numpy-git

(home-assistant) home assistant jail $ cd numpy-git 

(home-assistant) home assistant jail ~/numpy-git $ git checkout v1.26.0

(home-assistant) home assistant jail ~/numpy-git $ git cherry-pick 040ed2d

(home-assistant) home assistant jail ~/numpy-git $ git submodule update --init

(home-assistant) home assistant jail ~/numpy-git $ cd ..

(home-assistant) home assistant jail $ pip install numpy-git/

Step 4: Install Home Assistant Link to heading

After that little detour, we’re ready to install HA.

(home-assistant) home assistant jail $ pip install homeassistant
# LOTS of dependencies will be installed

(home-assistant) home assistant jail $ which hass
/usr/home/homeassistant/home-assistant/bin/hass

(home-assistant) home assistant jail $ hass --version
2023.12.1

Hopefully nothing else will fail at this step. If it does, it is most likely going to be a dependency that fails to install on FreeBSD.

Step 5: Start Home Assistant Link to heading

The initial run of hass will install further dependencies. The output of this command will let you know if there are other dependencies that need to be manually installed.

(home-assistant) home assistant jail $ hass -v --ignore-os-check
# Again, lots of dependencies will be installed.

If all goes well… Link to heading

After several minutes, you can go to xx.xx.xx.xx:8123 and be greeted by the Home Assistant landing page.

Where to from here? Link to heading

My next steps are to get Zigbee and ESPHome up and running so that I can control other devices around the house.

But this is enough for one night.