Manual Guide

This guide is based on the Manual Installation for a Raspberry Pi, also referred to as the "Advanced Guide" for a virtual environment install.

Creating a jail

Starting with FreeNAS 11.2 new jails can be created using the GUI. This can be an advantage if you'd like to customize many options. To quickly create a jail with basic settings, it is much quicker to use the console.

TrueNAS Core 12 / FreeBSD 12.1-RELEASE

iocage create -r 12.1-RELEASE dhcp=on bpf=yes vnet=on boot=on allow_raw_sockets=1 --name homeassistant

Install system dependencies

Access the jail console. Replace $jail with the name you chose. If you don’t know which name you have given the jail, you can use the iocage list command to check.

iocage console $jail

Install the suggested packages.

pkg install -y autoconf bash ca_root_nss ffmpeg gcc gmake pkgconf python38 py38-sqlite3 wget zip

Create a user account

Typically, the username is similar to the name of the service running inside the jail. Also, the user_id usually matches the default port number used by the service. Here I'm using the username homeassistant with a UID of 8123, matching the default port. Since this account is only used for running Home Assistant Core inside this jail, -w no is used to disable password login. I also create home directory to use as a location for the configuration. The argument -G dialout adds the user to the dialout group as required for using for USB Z-Wave and Zigbee controllers.

Create a home directory and add the $homeassistant_user

install -d -g 8123 -o 8123 -m 775 -- /home/homeassistant
pw adduser -u 8123 -n homeassistant -d /home/homeassistant -w no -s /usr/local/bin/bash -G dialer

Installing Home Assistant Core

Create a directory owned by the $homeassistant_user, to be used for the Home Assistant Core virtualenv.

install -d -g homeassistant -o homeassistant -m 775 -- /usr/local/share/homeassistant

Next, switch to the $homeassistant_user account, then create and activate the virtual environment for Home Assistant Core.

su - homeassistant
python3.8 -m venv /usr/local/share/homeassistant
source /usr/local/share/homeassistant/bin/activate

Once you have activated the virtual environment, upgrade pip while install some required Python packages.

pip install --upgrade pip wheel

Now install Home Assistant Core itself!

pip install homeassistant

While still in the venv, use the ensure_config script to populate the configuration directory.

hass --script ensure_config

Next, using the check_config script, we can make Home Assistant finish installing the initial dependencies.

hass --script check_config

Finally start Home Assistant

hass

When Home Assistant has started, you can reach your installation on http://ipaddress:8123.

Press Ctrl C to exit Home Assistant. Then deactivate venv and logout of the Home Assistant user.

deactivate && exit

Auto-start and Running Home Assistant Core as a Daemon ( service )

Upgrade FreeBSD system packages

iocage console $jail
pkg update && pkg upgrade

Upgrading Home Assistant Core

To update to the latest version of Home Assistant follow these simple steps:

su - homeassistant
source /usr/local/share/homeassistant/bin/activate
pip install --upgrade homeassistant

Once the last command executes, restart Home Assistant to apply the latest updates. Please keep in mind that some updates may take longer to start up than others. If Home Assistant fails to start, make sure you check the Breaking Changes from the Release Notes.

Run a specific version

In the event that a Home Assistant version doesn't play well with your hardware setup, you can downgrade to a previous release.

su - homeassistant
source /usr/local/share/homeassistant/bin/activate
pip install homeassistant==0.XX.X

Run the beta version

If you would like to test next release before anyone else, you can install the beta version released every two weeks, for example:

su - homeassistant
source /usr/local/share/homeassistant/bin/activate
pip install --pre --upgrade homeassistant

Run the development version

If you want to stay on the bleeding-edge Home Assistant development branch, you can upgrade to dev.

The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption.

su - homeassistant
source /usr/local/share/homeassistant/bin/activate
pip install --upgrade git+git://github.com/home-assistant/home-assistant.git@dev

Backup Home-Assistant config directory using `zip`

zip may not installed by default. To use this command you will need to first install zip

pkg update && pkg install -y zip

create backup as user homeassistant

iocage console $jail

su - homeassistant
zip -9 -q -r homeassistant-backup.zip .homeassistant -x"*/components/*" -x"*/deps/*" -x"*/home-assistant.log" -x"*/.cache/*" -x"*/__pycache__*/"

Activating the virtual environment

When instructions tell you to activate the virtual environment, the following commands will do this:

su - homeassistant
source /usr/local/share/homeassistant/bin/activate

Notice the prompt change to (homeassistant) [homeassistant@homeassistant ~]$ when the virtualenv is activated.

root@homeassistant:~ # su - homeassistant
[homeassistant@homeassistant ~]$ source /usr/local/share/homeassistant/bin/activate
(homeassistant) [homeassistant@homeassistant ~]$