Install Unifi under TrueNAS

Introduction

The UniFi Controller Management interface enables the management of UniFi devices and the display of network statistics.
The software is often installed on a Windows or Mac PC, but does not provide a solid foundation for long-term operation.
Since FreeBSD jails are so lean and FreeBSD is also supported by Ubiquiti, it makes sense to install it there.
If we're going to do it, let's do it right.

unifi1

Goals

The aim of this guide is to operate a Unifi controller based on TrueNAS or FreeBSD. Without jail, a pkg install unifi8 is sufficient and the topic is done. However, to make it even more perfect, especially with regard to the independence of the settings from the jail, we will go into more detail here.

NEW: For the very impatient I have a console only section. There are only commands, no explanations.

Last update:

04.02.2024: Final Version, minor adjustments
23.01.2024: Initial Version

Requirements

TrueNAS Core or pure FreeBSD server with iocage installed
IP address of the UNIFI jail is known
Hostname of the UNIFI jail is known (e.g. unifi.domain.local) and accessible via internal DNS

In general, such services should be set up in a separate environment. This makes not only security but also maintenance much easier. Jails can be backed up relatively easily and only the packages that are absolutely necessary are installed.

Diagram

The local setup looks like this:

                    ┌───────────────────────────────────────────┐
                    │   TrueNAS              Optional:          │
                    │ ┌──────────────────┐  ┌─────────────────┐ │
                    │ │ jail/unifi       │  │ tank/jail_data  │ │
LAN: 0.0.0.0:8443  ─┼─┼─► unifi  ────────┼──┼─► unifi/data    │ │
                    │ └──────────────────┘  └─────────────────┘ │
                    └───────────────────────────────────────────┘

Create jail

A separate jail is required if further web applications are to be built on Nginx/PHP.
Here we use web as the jail name.

Optional: Data directories

This is more for advanced users who already have some experience.

How certain data directories are stored outside the jail is explained here.
The following directories are required:

└── /mnt/tank/jails_data
    └── unifi
        └── data  # Storage for data (in the jail: /usr/local/share/java/unifi/data with id:975/unifi)

Optional: Create User

If the data is to be stored outside the jail, the authorisations must be appropriate and are explained in a separate article. The user and group name: unifi with the ID: 975 is required here.

Unifi can alternatively be restored excellently from a backup (unf) file.

Set up jail

The webshell in TrueNAS is sufficient for simple configurations, so SSH remains deactivated this time.

Jail start: TrueNAS / Jails / unifi / Start
Jail Shell open: TrueNAS / Jails / unifi / Shell

Customise package source

Package sources should be customised, see separate article.

Install packages & activate services

Now update the package source with pkg update and then install the required packages with pkg install -y unifi8.
Activate the service with service unifi enable so that it starts automatically when the jail is started.

Unifi

Create configuration

Hooray, no configuration is required, everything is created automatically at the first start.

Start services

We have now reached the end of the preparations and Unifi is started with service unifi start.

Registration

Unifi is now called up for the first time to set up the network.
To do this, use your favourite browser to call up the IP or host name of the Gitea jail: https://IP:8443 oder http://HOSTNAME:8443

unifi

Backup

Backups are performed automatically once a week by the UNIFI software.
These are stored in the folder /usr/local/share/java/unifi/data/backup.

Console

pkg install -y unifi8
service unifi enable
service unifi start

Voilá