Warning

These instructions have been deprecated and re-written for a newer version of Home Assistant.

They are only kept here for reference purposes.

Introduction Link to heading

Welcome to the 2024.6 version of running Home Assistant in a FreeBSD Bastille Jail. This page is here to provide a walkthrough for anyone wanting to run Home Assistant on FreeBSD for the first time, or provide guidance on what needs to be installed manually if you are upgrading from a previous release of HA.

Some of these instructions are copied forward from my previous posts on setting up the jail and creating an rc script for HA. My aim is provide a single page containing everything that a new user needs to install HA Core.

If you have any suggestions or notice any errors, please let me know by email: ‘blog’ at ’the primary-domain.com’ or via mastodon: @brendan@mastodon.brendans-bits.com

Note
If you have already set up the jail, homeassistant user, and installed pyenv, you can skip straight to Upgrading

Software versions Link to heading

  • FreeBSD 14.0
  • Bastille 0.10.20231125
  • Python 3.12.2 (installed in a python virtual environment)
  • Home Assistant Core 2024.6.1
Note

These instructions install the core version of HA.

You will need to install additional software manually. For example:

The supervisor and add-ons do not work with this method because they are installed in docker containers.

New installations - start here Link to heading

Setting up the host Link to heading

First we create the jail:

# bastille create -V home-assistant-test 14.0-RELEASE "DHCP SLAAC" igb0

# bastille console home-assistant-test

I prefer to use VNET jails so that I can assign IP addresses later.

Setting up the jail Link to heading

Jail dependencies Link to heading

First, we install some required dependencies:

# pkg update

# pkg install \
    bash \
    ca_root_nss \
    cmake \
    ffmpeg \
    gcc \
    git \
    gmake \
    libjpeg-turbo \
    nasm \
    openblas \
    openjpeg \
    pkgconf \
    pyenv \
    rust \
    sqlite3 \
    vim

Create an rc script for HA Link to heading

If you are installing HA for the first time, you may want to have FreeBSD’s rc system manage HA.

Create a new script file in the jail at /usr/local/etc/rc.d/homeassistant. Copy the content from https://brew.bsd.cafe/brendans_bits/freebsd-home-assistant-rc-script/src/commit/a663e77efe19910b8ac927d781a1480932b269ea/usr/local/etc/rc.d/homeassistant into this script. (Thanks to @stefano@bsd.cafe for hosting https://brew.bsd.cafe)

Add the following lines to the jail’s /etc/rc.conf:

homeassistant_enable="YES"
homeassistant_environment="/home/homeassistant/HA-2024.6"
homeassistant_log_folder="/var/log/homeassistant"
homeassistant_config_folder="/home/homeassistant/.homeassistant"
homeassistant_run_options="--verbose"

Setting up a user Link to heading

Then we create a dedicated user for Home Assistant:

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

# pw groupmod dialer -m homeassistant

# chmod 770 /home/homeassistant

# pw usermod homeassistant -s /usr/local/bin/bash

I prefer to use bash as my shell and the rest of the commands assume that you are also using bash.

Installing python for the user Link to heading

These instructions are taken from decuser over at the FreeBSD forums

We need to switch to the homeassistant user and install Python 3.12 using pyenv:

# su - homeassistant

$ pyenv install 3.12.2

$ pyenv global 3.12.2

$ pyenv init
# Load pyenv automatically by appending
# the following to 
# your shell's login startup file (for login shells)
# and your shell's interactive startup file (for interactive shells) :

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Restart your shell for the changes to take effect.

You will have to add the following lines to ~/.bashrc and ~/.profile

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Finally, we leave the homeassistant use shell and switch back into it to check that pyenv has loaded its shims correctly:

$ exit

# su - homeassistant

$ echo $PATH
/home/homeassistant/.pyenv/shims:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/home/homeassistant/bin

$ python --version
Python 3.12.3

Upgrading - start here Link to heading

Setting up a python virtual environment Link to heading

If you were able to successfully install Python 3.12, you can create a virtual environment to install Home Assistant.

$ mkdir HA-2024.6

$ cd HA-2024.6

$ python -m venv .

$ source bin/activate

I choose to name the python virtual environment according to the version of HomeAssistant that I plan to install in that PVE.

If all goes well, you will notice your shell change to:

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

This indicates that the home-assistant environment is being used.

We update pip and install wheel:

$ pip install --upgrade pip

$ pip install wheel

Setting up additional python dependencies Link to heading

There are three packages that do not automatically install correctly for HA Core 2024.6.

mutagen (checked 2024-06-10) Link to heading 
$ pip install mutagen

Note: HA-Core started up without installing this dependency, but the console showed this output:

2024-06-10 17:03:43.702 ERROR (MainThread) [homeassistant.setup] Error during setup of component conversation
Traceback (most recent call last):
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/setup.py", line 402, in _async_setup_component
    result = await task
             ^^^^^^^^^^
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/components/conversation/__init__.py", line 195, in async_setup
    from homeassistant.components.assist_pipeline import (  # pylint: disable=import-outside-toplevel
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/components/assist_pipeline/__init__.py", line 21, in <module>
    from .pipeline import (
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/components/assist_pipeline/pipeline.py", line 24, in <module>
    from homeassistant.components import (
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/components/tts/__init__.py", line 22, in <module>
    import mutagen
ModuleNotFoundError: No module named 'mutagen'

2024-06-10 17:03:45.695 ERROR (MainThread) [homeassistant.setup] Setup failed for 'tts': Unable to import component: No module named 'mutagen'
Traceback (most recent call last):
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/setup.py", line 320, in _async_setup_component
    component = await integration.async_get_component()
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/loader.py", line 1012, in async_get_component
    self._component_future.result()
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/loader.py", line 992, in async_get_component
    comp = await self.hass.async_add_import_executor_job(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/homeassistant/.pyenv/versions/3.12.2/lib/python3.12/concurrent/futures/thread.py", line 58, in run
    result = self.fn(*self.args, **self.kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/loader.py", line 1052, in _get_component
    ComponentProtocol, importlib.import_module(self.pkg_path)
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/util/loop.py", line 131, in protected_loop_func
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/home/homeassistant/.pyenv/versions/3.12.2/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 995, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/usr/home/homeassistant/HA-2024.6/lib/python3.12/site-packages/homeassistant/components/tts/__init__.py", line 22, in <module>
    import mutagen
ModuleNotFoundError: No module named 'mutagen'
python-isal (checked 2024-06-10) Link to heading

One of the dependencies of HA 2024.6 now requires python-isal which is not built for FreeBSD. But big thanks go to @jan@jit.social for submitting a pull request to the project which now allows us to build this for FreeBSD and fixing up the installed version number so that this can be installed for HA 2024.6.

$ git clone https://github.com/pycompression/python-isal.git

$ cd python-isal

$ sed -i '' "s@1.7.0-dev@1.6.1@" setup.py

$ git submodule update --init --recursive

$ pip install .
webrtc-noise-gain (checked 2024-06-10) Link to heading

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

$ pip install git+https://github.com/rhasspy/webrtc-noise-gain.git@a5ea46ffa29e76d5bde2b0bafaa28bee21cb7415

This is a known issue.

numpy (checked 2024-06-10) Link to heading

You need to install numpy manually from the instructions here

$ git clone https://github.com/numpy/numpy.git numpy-git

$ cd numpy-git 

$ git checkout v1.26.0

$ git cherry-pick 040ed2d

$ git submodule update --init

$ cd ..

$ pip install numpy-git/

Installing Home Assistant Link to heading

Finally, we’re ready to install Home Assistant.

Stop any existing HA installations (if you are upgrading from a previous version) Link to heading

If you are upgrading from a previous version of HA Core, you need to stop any HA service that is running.

Please make sure you have a backup of your HA configuration folder before installing any new version of HA. For example:

$ cp -r .homeassistant/ .homeassistant-backup/

Install and test the new version of HA Link to heading

We’re going to let HA install the rest of its dependencies and check that it is working

$ pip install homeassistant~=2024.6.0

$ hass --ignore-os-check -v -c /home/homeassistant/.homeassistant

hass will now install more dependencies.

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

HA Landing Page

Check for any missing custom dependencies Link to heading

If you have installed any custom components that require additional dependencies, you will see errors when hass is running for the first time. For example, I use a postgresql database as my recording backend and when I upgraded my version of HA I got this error because I had forgotten to reinstall psycopg2:

2024-04-18 23:23:57.868 ERROR (Recorder) [homeassistant.components.recorder.core] Error during connection setup: No module named 'psycopg2' (retrying in 3 seconds)
Traceback (most recent call last):
  File "/usr/home/homeassistant/HA-2024.4/lib/python3.12/site-packages/homeassistant/components/recorder/core.py", line 940, in _setup_recorder
    self._setup_connection()
  File "/usr/home/homeassistant/HA-2024.4/lib/python3.12/site-packages/homeassistant/components/recorder/core.py", line 1439, in _setup_connection
    self.engine = create_engine(self.db_url, **kwargs, future=True)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 2, in create_engine
  File "/usr/home/homeassistant/HA-2024.4/lib/python3.12/site-packages/sqlalchemy/util/deprecations.py", line 281, in warned
    return fn(*args, **kwargs)  # type: ignore[no-any-return]
           ^^^^^^^^^^^^^^^^^^^
  File "/usr/home/homeassistant/HA-2024.4/lib/python3.12/site-packages/sqlalchemy/engine/create.py", line 599, in create_engine
    dbapi = dbapi_meth(**dbapi_args)
            ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/home/homeassistant/HA-2024.4/lib/python3.12/site-packages/sqlalchemy/dialects/postgresql/psycopg2.py", line 690, in import_dbapi
    import psycopg2
ModuleNotFoundError: No module named 'psycopg2'

Let service manage HA Link to heading

Make sure that you have stopped any running instances of hass.

Then let service start homeassistant:

(as jail root) # service homeassistant start

Check your logs while you are testing the new version of HA to check for any missing dependencies:

# tail -f /var/log/homeassistant/homeassistant-daemon.log

Credits and thanks Link to heading

These instructions build upon the guides written by Dan Langille and Engr. Rez Cab.

Thanks goes to:

  • @justdude@mastodon.nl for picking up a missing step in a previous version of this post
  • @jan@jit.social for:
    • recommending ca_root_nss and libjpeg-turbo as dependencies, and
    • submitting a PR to get python-isal build on FreeBSD and helping me with the installation instructions.