Installing the UniFi Controller on the Raspberry Pi

With this tutorial, we will be showing you the process of installing the UniFi Controller on a Raspberry Pi

Raspberry Pi UniFi Controller
UniFi is a range of network devices created by Ubiquiti. These devices range from Wi-Fi access points to security gateways and switches.

Setting up the UniFi software on a Raspberry Pi is a fairly straightforward process as it just relies on the multi-platform Java runtime to run.

Using the UniFi network controller, you can manage all the UniFi devices that are a part of your network. You will also be able to use this dashboard to see the statistics of your UniFi network.

Equipment List

Below is a list of the equipment that you will need to set up the Unifi Network Controller software on your Raspberry Pi

Recommended

Raspberry Pi 1, 2, 3 or 4

Micro SD Card

Power Supply

Ethernet Cord or WiFi dongle (The Pi 3 and 4 has WiFi inbuilt)

Optional

Raspberry Pi Case

This tutorial on setting up the UniFi Network Controller was tested on a Raspberry Pi 4 running the latest version of Raspbian Buster.

Preparing your Raspberry Pi for the UniFi Controller

In this section, we will be preparing the operating system so it can run the UniFi software.

1. The first thing you should do is ensure that your Raspberry Pi is running up to date packages.

To update all packages, you will be required to run the following command.

sudo apt update
sudo apt upgrade

2. Next, we need to install version 8 of the Java runtime environment to our Raspberry Pi by running the command below.

We need to install Java as the UniFi Network controller requires it to run.

sudo apt install openjdk-8-jre-headless

As of the time of posting, UniFi does not support newer versions of the Java runtime.

3. To improve the startup speed of the UniFi controller software on our Raspberry Pi, we need to install rng-tools.

We will utilize this package to ensure the Raspberry Pi has enough entropy for the random number generation that the UniFi software uses.

sudo apt install rng-tools

4. We now need to make a slight change to the rng-tools configuration.

Begin editing the config file by running the following command.

sudo nano /etc/default/rng-tools

5. Within this file, find and uncomment the following line.

Find

#HRNGDEVICE=/dev/hwrng

Replace With

HRNGDEVICE=/dev/hwrng

Once you have made the change, save the file by pressing CTRL + X, then Y, followed by ENTER.

6. Finally, restart the rng-tools service by running the command below.

sudo systemctl restart rng-tools

Once the service has finished restarting, it should now be safe to proceed to the next section of this guide.

Installing the UniFi Controller to the Raspberry Pi

1. Our first task is to add the UniFi repository to our sources list.

We can achieve this by running the command below.

echo 'deb https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

2. We now need to add the repositories GPG key by using the following command.

sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ui.com/unifi/unifi-repo.gpg

The GPG key is what helps tell the package manager it is downloading the correct package.

3. As we made changes to the repositories, we need to now update the package list by running the command below.

sudo apt update

4. Now finally, we can install the Unifi Controller software to our Raspberry Pi by running the following command.

sudo apt install unifi

Installing UniFi through this method will automatically set up a service. This service will automatically start the UniFi software at boot.

First Boot of the UniFi Controller on your Raspberry Pi

In this section, we are going to walk you through the initial configuration steps of the UniFi software.

1. First, retrieve the local IP address for your Raspberry Pi.

If you have terminal access to your Pi, you can use the following command.

hostname -I

2. With your Raspberry Pi’s IP address handy, go to the following web address in your favorite web browser.

https://[IPADDRESS]:8443

If you run into a certificate error, it is safe to ignore it as we know what device we are connecting to.

3. The first step requires you to give a name for your Raspberry Pi powered UniFi controller (1.).

You are also required to agree to the end-user license agreement and terms of service from UniFi, once you have read through them, click the checkbox (2.).

Once all done, click the “Next” button (3.) to proceed.

Set Name of UniFi Network

4. Next, you will need to sign in to your Ubiquiti account (1.).

If you don’t already have an account, you can register at the Ubiquiti website.

Once you have entered your login details, proceed by clicking the “Next” button.

Sign in to Ubitquiti Account

5. Tweak the settings on this page that best suits your needs.

Once configured, click the “Next” button.

UniFi Network Setup

6. Use this screen to connect your Pi UniFi Network controller to the devices on your network.

To proceed, click the “Next” button.

Connect Raspberry Pi to UniFi Devices

7. Now give your new Wi-Fi network a name and a password.

Once you have configured your WiFi details (1.), click the “Next” button to proceed (2.).

Setup UniFi WiFi Details

8. This final screen will get you to review all your settings.

You will also be able to use this screen to set both the country and timezone (1.). Make sure you set these before continuing.

Once you have verified everything is correct, you can now click the “Finish” button (2.) to finish the setup process.

Review Raspberry Pi UniFi Configuration Settings

7. At this point, you should now have successfully set up the UniFi network controller on your Raspberry Pi.

Raspberry Pi UniFi Dashboard

If you have run into any issues with setting up the UniFi software, feel free to drop a comment below.

10 Comments

  1. Avatar for Christoph
    Christoph on

    The only tutorial which worked for me.
    Many thanks!

  2. Avatar for Zeke
    Zeke on

    great step by step instructions! works like a charm!

  3. Avatar for Frank
    Frank on

    I always install UFW on my Rpis. That caused me a bit of trouble this time. But for those that want a firewall, I had to open ports 22, 8080, 8443, 8843, 8880, 8881 and 27117 (per an old post in the Ubiquiti forums).

    Thanks for the very helpful instructions!

  4. Avatar for Gabe
    Gabe on

    I spent a long time trying to set the ubiquiti controller up on my Windows PC to no avail. This tutorial was easy and I was up and running in no time!

    Thank you so much!

  5. Avatar for sean flynn
    sean flynn on

    That fixed it, thanks Emmet.
    Kind of disconcerting that certain mirrors have bad images.

  6. Avatar for sean flynn
    sean flynn on

    When I get to “sudo apt install unifi” it fails to install with many messages like the following:
    File has unexpected size (32768 != 31176). Mirror sync in progress? [IP: SNIPPED]
    Any ideas? TIA

    1. Avatar for Emmet
      Emmet on Editor

      Hi Sean,

      That looks like there is an issue with the mirror the operating system is trying to download from.

      You can either wait and hope it eventually fixes itself (Will likely need to run another sudo apt update) or change it to another mirror manually.

      You can follow our guide on changing the Raspbian repository if you decide to go down that route.

      Cheers,
      Emmet

  7. Avatar for Jonathan
    Jonathan on

    On step 2 under installing the UniFi controller software I keep getting the following message when running the sudo apt-get update command:

    N: Skipping acquire of configured file ‘ubiquiti/binary-arm64/Packages’ as repository ‘https://www.ui.com/downloads/unifi/debian stable InRelease’ doesn’t support architecture ‘arm64’

    I can’t seem to get past this and after googling around I can’t seem to find anyone with the answer to solve the issue either.

    Any thoughts?

    1. Avatar for Emmet
      Emmet on Editor

      Hi Jonathon,

      Are you trying to install this in a 64bit operating system?

      Cheers,
      Emmet

    2. Avatar for Jonathan
      Jonathan on

      Emmet,

      I was using 64 bit ubuntu but I went back to Raspberrian Lite and it works great now!

      Thanks!

      Jonathan

Leave a Reply

Your email address will not be published. Required fields are marked *