Installing the UniFi Controller on the Raspberry Pi

by Emmet

Updated Apr 08, 2024

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

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.

Please note that before proceeding you will need to be running a 64-bit version of Raspberry Pi OS for this tutorial to work. Recent changes to UniFi have broken support for 32-bit operating systems.

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

Optional

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

Preparing your Raspberry Pi for the UniFi Controller

In this section, we will prepare the operating system to run the UniFi software. These steps mainly revolve around getting the database server UniFi requires installed on your Raspberry Pi.

Getting Ready

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

Adding Entropy using rng-tools

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

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

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

5. 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 LibSSL1.1

7. Due to the version of MongoDB that we will be utilizing, we will need to install LibSSL 1.1 to our Raspberry Pi.

You can install this release of LibSSL by using the following command in the terminal.

sudo apt install libssl1.1

Installing MongoDB to your Raspberry Pi for the UniFi Controller

8. To use the UniFi Controller on your Raspberry Pi, we will need to install MongoDB.

This is the database server that UniFi uses to store all of its data. As we can’t rely on the package repository, we will need to follow some additional steps.

For this first step, we will download MongoDB 4.4.18 to our Pi. We are installing 4.4 as this is currently the only supported release for the UniFi Controller that is compatible with the Raspberry Pi.

wget https://repo.mongodb.org/apt/ubuntu/dists/focal/mongodb-org/4.4/multiverse/binary-arm64/mongodb-org-server_4.4.18_arm64.deb -O mongodb.deb

9. Once the package is downloaded, install it by using the following command within the terminal.

sudo dpkg -i mongodb.deb

10. Now that we have installed the MongoDB server, set it to start when your Raspberry Pi boots using the command below.

sudo systemctl enable mongod

11. Finally, start MongoDB by running the command shown below in the terminal.

This will start the server immediately, so we won’t have to wait till our device restarts.

sudo systemctl start mongod

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 [arch=amd64 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 >/dev/null

You might notice that we are using “amd64” and not “arm64” or “armhf“. This is due to Ubiquiti not having their repository set up to mark “arm64” as compatible. However, it doesn’t hugely matter as, at the moment, it will still download files compatible with our Raspberry Pi.

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 version 17 of the OpenJDK runtime as well as the Unifi Controller software itself to our Raspberry Pi by running the following command.

sudo apt install openjdk-17-jre-headless unifi

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

Additionally, we are installing version 17 of the Java runtime environment as it is currently the only version supported by the UniFi controller.

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.

Ensure that you replace “<IPADDRES>” with the IP of your Raspberry Pi.

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.

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.

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

Once configured, click the “Next” button.

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

To proceed, click the “Next” button.

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

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.

Conclusion

Hopefully, at this point in the tutorial, you will now have the UniFi controller installed and running on your Raspberry Pi.

The Pi is a great base for your network controller as it can run 24/7 with little power.

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

Check out our many other Raspberry Pi tutorials to learn more about this versatile system.

179 Comments

ramzez on June 2, 2023 at 5:36 pm

Looks like a new update of unified 7.4 requires newer version of mongoDB and 64Bit OS, is that possible to update the article on how to get it running? Thank you! Update just failed even with setting Kernel back to 64bit.

Reply
1. Emmet on June 3, 2023 at 1:35 am
  
  Editor
  
  Hi Ramzes,
  
  Thank you for alerting me to this. I quickly tested UniFi on a 64-bit operating system and have now updated the tutorial to reflect these changes.
  
  However, I have only been able to test this on a clean installation of the 64-bit release of Raspberry Pi OS. It may be safest to start fresh and restore your Uni-Fi configuration from a backup.
  
  The major changes are we are now installing a 64-bit release of MongoDB 3.6, and have adjusted the tutorial to install Java 11 that the controller now requires it. This verison of Java also means you can no longer use a 32-bit operating system.
  
  Cheers,
  Emmet
Jason on June 2, 2023 at 7:50 am

Hi mate,
Will receive my first ever Pi tomorrow and I’m quite nervous how to get this to work… Would this support recent versions of the unifi controller/ network manager software? I thought they need java 11 now?
Cheers
Jason

Reply
1. Emmet on June 3, 2023 at 1:40 am
  
  Editor
  
  Hi Jason,
  
  Glad you managed to get your hands on a Raspberry Pi! They are very versatile pieces of hardware and are pretty easy to use.
  
  I have actually just updated this tutorial to work with the latest release of the Unifi controller! Just ensure that you use the 64-bit release of Raspberry Pi OS when you set this up.
  
  Cheers,
  Emmet
Louis on June 2, 2023 at 7:27 am

The most recent version of Unifi controller no longer supports MongoDB version 2.4.14 which is the highest version i can get to on my raspberry pi 3 B with 32 bit OS Lite. can you post a way to downgrade the Unifi controller to 7.3.83 or try to find a way to update MongoDB. I have not got a back up for my controller which is why a clean install is not an option. Any help would be appreciated.

Reply
1. Emmet on June 3, 2023 at 1:41 am
  
  Editor
  Hi Louis,
  
  Sorry about the issues that you are facing with the latest update to the Unifi Controller. You should be able to downgrade to the working release by using the following two commands.
  
  wget https://dl.ui.com/unifi/7.3.83/unifi_sysvinit_all.deb sudo dpkg -i unifi_sysvinit_all.deb
  
  Cheers,
  Emmet
Toan Nguyen on June 2, 2023 at 1:30 am

I got this when install unifi. Please have a look into it!

Setting up unifi (7.4.156-21011-1) …
Created symlink /etc/systemd/system/multi-user.target.wants/unifi.service → /lib/systemd/system/unifi.service.
Job for unifi.service failed because the control process exited with error code.

Reply
1. Emmet on June 3, 2023 at 2:02 am
  
  Editor
  
  Hi Tony,
  
  Unfortunately changes to Unifi now means you require a 64-bit operating system. The tutorial has been updated to reflect these changes.
  
  Cheers,
  Emmet
Binzz on May 31, 2023 at 2:09 pm

Emmet, thank you very much this tutorial! Like others mentioned, this is the only tutorial that seems to work these days. My Pi 4’s SD card died and after finding your tutorial I had my Pi 4 back up and running very quickly after a config backup.

Reply
Jan on May 30, 2023 at 7:53 am

Thank you so much! this is the only guide I found that acually worked. It also fixed all my bloody mongodb problems. Thanks

Reply
nizzbq4 on May 28, 2023 at 2:48 am

Thanks for this excellent tutorial!!! Very well laid out and simple to follow. Had my Pi 4 up and controlling my Unifi equipment very quickly (after a config restore).

Reply
Chris on May 25, 2023 at 3:49 pm

Emmet. Thank you much for the update. I’m currently running into an issue with pihole unbound service failed. Would you mind helping?

Reply
1. Emmet on May 25, 2023 at 4:57 pm
  
  Editor
  
  Hi Chris,
  
  Sorry to hear that you are having issue. Did this happen to occur after installing the UniFi controller? If so, could you please show any errors that are occurring?
  
  Cheers,
  Emmet
Gary Byers on May 22, 2023 at 3:22 am

Emmet,

Great tutorial!! Had a real hard time getting the latest and greatest to work. I went with your tutorial this morning and loaded and successfully set up the unifi controller for my latest customer. I have used this setup 5-6 times in the past with different customers and it had always worked but was running into brick walls on this one. Once I followed your newest gig, it worked first time. Thanks for this and will bookmark it for future reference.

Gary

Reply
O on May 14, 2023 at 4:12 am

Thanks!

Reply
Chris on April 24, 2023 at 3:23 am

I’d followed the step. However, the current version of the Unifi controller does not support it. Thank you!

Reply
1. Emmet on April 24, 2023 at 9:13 pm
  
  Editor
  
  Hi Chris,
  
  A recent change to Raspberry Pi OS may of broken the original steps. I have updated the guide with additional steps that should work around the latest issue.
  
  Cheers,
  Emmet
piman on April 24, 2023 at 1:37 am

Heads up, there appears to be an issue with a recent update of the Pi and operating with the 64 bit kernel. Stopped working for me recently. Solution is below.

https://community.ui.com/questions/Unifi-on-Raspberry-Pi-stopped-working-after-update/bc6604ce-ad18-4b7e-9622-f7172f424e03?page=0

Reply
1. Emmet on April 24, 2023 at 9:12 pm
  
  Editor
  
  Hi Piman,
  
  Thank you for the heads up about this issue. I have updated the guide to implement the workaround.
  
  Cheers,
  Emmet
Dan on April 23, 2023 at 11:52 pm

Many hours saved, thank you.

Reply
Opcom on December 13, 2022 at 8:05 am

Great, thank You

Reply
Marco on November 4, 2022 at 8:18 am

You are the greatest!!!
Thanks a lot Emmet, worked for me: Updated Pi to the buster Version and the Unifi Controller from Version 6.4.54 to 7.2.95
And now I try to get the L3 adoption fixed…

Reply
lovepi on November 1, 2022 at 1:50 am

Thanks — ran from start to finish on a 3B and working great. 32bit dietpi base install.

Reply

Thanks for the updated tutorial.
Unfortunately still not there. something to do with 32 vs 64 bit Raspbian OS. I am using 64 bit.
First error occurs in step 6 under the “Extra Steps for Raspberry Pi OS Bullseye” section:

$ sudo apt update
[[SNIPPED]
N: Skipping acquire of configured file 'main/binary-arm64/Packages' as repository 'http://archive.raspbian.org/raspbian stretch InRelease' doesn't support architecture 'arm64'

Second error on step 3 of the “Installing the UniFi Controller to the Raspberry Pi” section:

$ sudo apt update
. . .
All packages are up to date.
N: Skipping acquire of configured file 'main/binary-arm64/Packages' as repository 'http://archive.raspbian.org/raspbian stretch InRelease' doesn't support architecture 'arm64'
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'

So step 4 does not work:

$ sudo apt install openjdk-8-jre-headless unifi
. . .
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.

So that's as far as I can get for now.

Emmet on October 31, 2022 at 2:53 pm

Editor

Hi Tim,

At this stage this tutorial will only work with a 32-bit release of Raspberry Pi OS.

Cheers,
Emmet

Tim on October 31, 2022 at 3:06 am
When to apply this excellent looking post to my new RPi 4B and ran into two problems right off the bat.
#1 openjdk-8-jre-headless is not available in the Buster repo’s any more. I installed openjdk-11-jre-headless just to see how far I could get.
#2 When I added the stretch repo and did the sudo apt update I get this:
```
Get:6 http://archive.raspbian.org/raspbian stretch InRelease [15.0 kB]
Err:6 http://archive.raspbian.org/raspbian stretch InRelease
  The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 9165938D90FDDD2E
Reading package lists... Done
W: GPG error: http://archive.raspbian.org/raspbian stretch InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 9165938D90FDDD2E
E: The repository 'http://archive.raspbian.org/raspbian stretch InRelease' is not signed.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.
```
So it looks like there needs to be an update to this post or an update the unifi and PI OS to get unifi working on the Pi.

Reply
1. Emmet on October 31, 2022 at 1:34 pm
  
  Editor
  
  Hi Tim,
  
  Thank you for the heads up about this issue.
  
  I have re-adjusted the tutorial so that the Raspbian repository will not work correctly and you should now be able to proceed with the install. It looks like in a recent release the GPG key belonging to that repository stopped being shipped with the operating system.
  
  I have also re-adjusted the install order so that OpenJDK 8 will now be installed from the older stretch repository alongside mongodb. Since OpenJDK 8 is EOL im not hugely surprised it has been removed from the repository, but sadly in this case it is required for UniFi to function.
  
  Cheers,
  Emmet
mike on October 31, 2022 at 1:43 am

openjdk-8-jre-headless is no longer available.
sudo apt install openjdk-8-jre-headless
E: Unable to locate package openjdk-8-jre-headless

Reply
1. Emmet on October 31, 2022 at 1:38 pm
  
  Editor
  
  Hi Mike,
  
  Please try re-running through the tutorial. The guide has been updated to work around this issue.
  
  Cheers,
  Emmet
swansinflight on October 8, 2022 at 7:51 pm

Life saver. Had to update my Pi2 from Buster to Bullseye for PiHole reasons, and this part was my sticking point – much appreciated!!!!

Reply