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 Raspberry Pi OS Bullseye.

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-debian

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

Find

#HRNGDEVICE=/dev/hwrng

Replace With

HRNGDEVICE=/dev/hwrng

By uncommenting this line, we are adding to the amount of entropy (The amount of randomness) that the system has available.

The Raspberry Pi features an integrated random number generator that we can utilize to increase the entropy pool.

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

7. 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.

Extra Steps for Raspberry Pi OS Bullseye

When trying to install the UniFi controller on Raspberry Pi OS Bullseye, you will run into issues with the mongodb package not being available.

To work around this issue we can add the old stretch repository as a source and pin it so that none of its packages will take preference.

Ideally, mongodb will be made available from the official repository, but for now, we will have to work around it

1. Let us start by creating a preferences file for the apt package manager. This file will allow us to modify the priority of the repository that we are about to add.

You can start writing this preferences file by using the following command.

sudo nano /etc/apt/preferences.d/99stretch-mongodb.pref

2. Within this file, you will need to type in the following lines.

#Never Prefer packages from Stretch
Package: *
Pin: release n=stretch
Pin-Priority: 1

These lines tell the apt package manager a few different things. First, we use the wildcard for our package name. The wildcard means our following rules will apply to all packages available.

The following two lines are what we use to set a priority for packages from our new repository. By setting the “pin-priority” to 1, we ensure that apt will prefer other packages over ones from the Stretch repository.

3. Once you have made these changes to the file, you can save and quit by pressing CTRL + X, then Y, followed by the ENTER key.

4. Now that we have created our new preferences file, we can now add our repository that contains mongodb.

To add this repository we will be creating a new file called “stretch_mongodb.list” in the “/etc/apt/sources.list.d/” directory.

Using this simple one liner, we can echo the repository string and add it straight into this new file without having to use a text editor like nano.

echo "deb http://archive.raspbian.org/raspbian stretch main" | sudo tee /etc/apt/sources.list.d/stretch_mongodb.list

5. As we have made changes to the package sources, we need to update the package list.

You can update the package list by using the following command on your Raspberry Pi.

sudo apt update

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 [signed-by=/usr/share/keyrings/ubiquiti-archive-keyring.gpg] 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.

curl https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee /usr/share/keyrings/ubiquiti-archive-keyring.gpg >/dev/null

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.

46 Comments

  1. Avatar for Jorg
    Jorg on

    Great tutorial! Helped me get the unify controller (or NA nowadays) running in one go; thank you the great post!

    Cheers, Jorg.

  2. Avatar for Carsten Kochems
    Carsten Kochems on

    Only this Tutorial works, great 🙂

  3. Avatar for Wannes
    Wannes on

    Amazing tutorial! Worked perfectly on bullseye. I did have a problem at first but when I used ssh and just copied the commands, everything worked. So I recommend just copying the commands.
    Thanks again

  4. Avatar for ErshN8D
    ErshN8D on

    Unfortunately, this Tutorial does not work in Bullseye. The MongoDB was removed from OS packages.

  5. Avatar for Michael
    Michael on

    Hi,

    I’m testing the install and set up on a RPi 1B rev1 and rev 2 and both fail on the Unifi install (see terminal output below). I’m waiting to get some RPi 3 and 4s back from a job to test on a newer model but it would be good to have your thoughts.

    pi@rpi-server:~ $ sudo apt install unifi
    Reading package lists... Done
    Building dependency tree... Done
    Reading state information... Done
    Some packages could not be installed. This may mean that you have
    requested an impossible situation or if you are using the unstable
    distribution that some required packages have not yet been created
    or been moved out of Incoming.
    The following information may help to resolve the situation:
    
    The following packages have unmet dependencies:
     unifi : Depends: mongodb-server (>= 2.4.10) but it is not installable or
                      mongodb-10gen (>= 2.4.14) but it is not installable or
                      mongodb-org-server (>= 2.6.0) but it is not installable
             Depends: mongodb-server (< 1:4.0.0) but it is not installable or
                      mongodb-10gen (< 4.0.0) but it is not installable or
                      mongodb-org-server (< 4.0.0) but it is not installable
    E: Unable to correct problems, you have held broken packages.
    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Michael,

      The MongoDB package is missing from Raspberry Pi OS Bullseye. I am currently looking into a solution for this issue.

      For now it will probably be easier to stick with Raspberry Pi Buster.

      Cheers,
      Emmet

  6. Avatar for Martin
    Martin on

    Hi Emmett.
    I have used these instructions many times on buster with no issues at all but it seems they no longer be work on the latest bullseye release. Firstly they have changed the name of the rng-tools conf file to be rng-conf-debian, not the end of the world but there also does not seem to be an available version of mongodb in the repository so Unifi will not install and just fails every time.

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Martin,

      I am trying to look into whether there is a simple workaround for this issue. I will comment again if I find a good solution that doesn’t require an excessive amount of extra work.

      For anyone else reading this I would currently recommend that you stick with Raspberry Pi OS Buster for now. There is quite a few packages that are missing from the new Bullseye release.

      Cheers,
      Emmet

    2. Avatar for Emmet
      Emmet on
      Editor

      Hi Martin,

      I attached a new subsection that shows you how you can get mongodb to install again.

      This involves adding the Stretch repository is a package source. Its not the best way of fixing the issue but it is a valid workaround.

      Cheers,
      Emmet

  7. Avatar for Etienne
    Etienne on

    Hi.
    Great tutorial. Used it to setup the first time and working great. I recently updated and now i get “database migration in progress…” whe i connect to controller.
    Any idea on how to fix it.
    Thanks
    Etienne

    1. Avatar for Emmet
      Emmet on
      Editor

      HI Etienne,

      I believe that it should eventually work past this after some time. It should give you some indication of how it is progressing.

      IF it appears that the progress is stuck, you may want to consider checking to see that your Pi has enough spare disk space.

      Cheers,
      Emmet

  8. Avatar for Louis Apostolakis
    Louis Apostolakis on

    Thanks for the tutorial. However, unifi is not starting on boot. This is a new install of rpi and there is nothing else on the rpi besides unifi. How can I correct this?

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Louis,

      Can you try running the following command. It should give us an idea of whether the service is enabled or not.

      sudo systemctl status unifi

      If it reports that its not “enabled”, try running the following command.

      sudo systemctl enable unifi

      Cheers,
      Emmet

  9. Avatar for Stephanie
    Stephanie on

    This tutorial is FANTASTIC; the device is up an running!! Thank you so much. Question: is Pihole worth installing?

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Stephanie,

      Pi Hole is very good at what it does and is a fantastic network-wide ad blocker if that is something you after. As it is a relatively lightweight software, you can probably get away with running it alongside the UniFi software.

      Of course, Pi Hole is far from a perfect solution as there is only so far a DNS based adblocker can get you. For example, with the way YouTube ads work these days it is hard to just block a particular domain name.

      More traditional adblockers (Such as uBlock or Adguard) that run as an extension of a web browser have access to any of the data the web browser exposes allowing it to detect and block more complicated ads.

      However, remember that when blocking ads you are cutting off a revenue stream for that website, so please consider other ways of supporting that website if you can afford to do so.

      Cheers,
      Emmet

  10. Avatar for Thankful Dan
    Thankful Dan on

    Just want to add that you can navigate to the Unifi Controller UI by going to https://localhost:8443 just like in a Windows host machine, that way if you want your controller to be on a DHCP lease, you don’t have to constantly look up the IP.

    Great guide though, I wouldn’t have figured it out without this. Thank you.

  11. Avatar for Kaden
    Kaden on

    UniFi keeps giving me a “unifi cannot locate java home” error. I have gone through so many steps and tutorials that has been of no help. Has anyone seen this issue and found a fix for it?

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Kaden,

      If possible could you please copy and paste the whole error, or screenshot it?

      May give me a better idea of what exactly is going wrong.

      Cheers,
      Emmet

Leave a Reply

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