Setup Unifi Network Controller on a Raspberry Pi

Unifi access points from Ubiquiti cannot be configured like normal, standalone access points. They require a special network component called Unifi Controller. This controller is a piece of Software that allows configuration and monitoring of all Unifi access points within the network. This setup is intended for large deployments with many access points, for smaller deployments it is also possible to deploy the Unifi Controller onto a Raspberry Pi.

Raspberry Pi headless setup

Download the Raspian image from the Raspbian download page. As there will be no need for a Desktop environment, download the “Lite” version.

Extract the downloaded archive and transfer the image to an SD card.

There are many tools to copy the image to an SD card. Etcher is one of these handy tools that make this quite easy, but you are also able to use any other program to copy the image to the SD card – even good old “dd” would work fine for this.

Once the SD card has been created, there will be two partitions on it: “boot and “rootfs”. Depending on the OS used, only the boot partition might be mounted. The rootfs uses an ext filesystem which is not supported by Windows or macOS. The boot partition uses a FAT filesystem which is supported by all major operating systems.

On the “boot” partition, create an “ssh” file (without a file extension) to enable the ssh daemon.


Assuming the Raspberry Pi is already installed with Raspian (Debian for Raspberry Pi), the following repository can be added to install the required software and keep it up to date.

$ echo 'deb unifi5 ubiquiti' >/etc/apt/sources.list.d/unifi.list

When apt-get update is called, errors will be shown as a result of the missing gpg key. To install the missing gpg key run the following command. This will request and install the key with the ID “C0A52C50” from the keyserver “”.

$ apt-key adv --keyserver --recv C0A52C50

After installing the gpg key used to sign the packages, the package list can be updated.

$ apt-get update

To install the Ubiquiti UniFi server just install the “unifi” package which installs all the required packages as dependencies. At the time of writing, “unifi” requires Java 8, so openjdk 8 is also installed to fulfil this requirement. The JRE is, at the time of writing, not set as a dependency in the “unifi” package and so must be installed separately.

$ apt install unifi openjdk-8-jre-headless

All other dependencies are automatically selected by installing the “unifi” package. At the time of writing, “unifi” requires a JRE but the package manager chooses its default, a version currently not compatible with unifi. Selecting the correct JRE solves this issue.

Starting the Ubiquiti UniFi server

With the “unifi” package and the JRE installed, the service needs to be started. To do so, the package provides a unit-file for systemd to start and stop the service.

$ systemctl start unifi

To ensure the service is started at boot time, enable the service using systemctl.

$ systemctl enable unifi

The unit files will start the unifi daemon and all necesarry components like MongoDB automatically.

Access the web-frontend

To access the Web interface of the unifi controller, get the IP of the Raspberry Pi and open the address with port 8443 in your browser.

For example, if the Raspberry Pi has the IP, the following URL can be used to access the unifi web frontend.

Read more of my posts on my blog at

This entry was posted in Linux Administration and tagged , , . Bookmark the permalink.