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

edward on March 28, 2024 at 7:08 pm

I see that unifi is now at version 8.1, and seems a big update, now supports mongodb to v7.

Is it a simple update from v8 to v8.1 on the rpi as installed by this guide?

Reply
1. Emmet on March 28, 2024 at 10:05 pm
  
  Editor
  
  Hi Edward,
  
  The problem with newer versions of MongoDB is that they explicitly claim they do not support the Raspberry Pi and the version of ARM it uses in newer releases of MongoDB. On that note, I have updated the tutorial to at least use MongoDB 4.4 (The last one with support for the ARM processor the Pi uses).
  
  If you are using an older version of this tutorial, you should be fine continuing to run MongoDB 3.6 as that is still supported as of the latest release. It should be safe to update to the latest release by using “sudo apt update && sudo apt upgrade”. But as always, make a back up before you update.
  
  Kind regards,
  Emmet
2. Edward on March 30, 2024 at 8:40 pm
  
  Hi Emmet,
  
  Thank you for the great advice. I updated as you suggested and no issues going from v8 to v8.1 Just updated unifi and mongodb unchanged.
  
  Regards
  
  Edward
Wedge on March 26, 2024 at 2:05 pm

I am unable to install mongodb on my Pi4 running Raspbian 11 Bullseye. I have followed the instructions listed here and see the following error.
sudo dpkg -i libssl1.0.deb
dpkg: error processing archive libssl1.0.deb (–install):
package architecture (arm64) does not match system (armhf)
Errors were encountered while processing:
libssl1.0.deb

Reply
1. Emmet on March 26, 2024 at 4:31 pm
  
  Editor
  
  Hi Wedge,
  
  It appears that you are running a 32-bit version of Raspberry Pi OS.
  
  You must be running a 64-bit version for this tutorial to work.
  
  Kind regards,
  Emmet
2. Flavio on April 6, 2024 at 12:35 am
  
  Unfortunately I could not install today. Mongodb returns “mongod.service: Failed with result ‘signal’.”
  Tried mongodb 3.6 with no success.
  My Pi4 is 2mb, Bullseye OS 11 (64 bit). Any advice or tip, please ?
3. FLAVIO on April 8, 2024 at 9:16 pm
  
  Use the MongoDB version 4.4.18 instead of the newer version. Worked for me.
Raymond R. on February 26, 2024 at 10:54 am

Posting just to say “Thank you!”. I am a linux noob but know my way around. Your tutorial was straighforward and to the point. I do want to point out when trying to download the java and mongo files, it seems to get stuck on the IPv6 repos it attempts first. Once they attempt an IPv4 repo, files downloaded promptly. Not sure if others have experienced this but if so, please be patient!

Reply
richy on January 11, 2024 at 12:53 am

Hi Everyone,

I’ve bee trying for the past two weeks to get my Rasberry Pi 3b+ to work following this guide.

A fresh approach today worked perfectly.

Installed Bookworm 64 Bit Lite – No desktop.
Followed the guide – System working perfectly with no problems.
Its not sluggish – restored my current settings from my PC to the PI and current version of the Unifi Controller Network 8.0.26.

I was going to sell all my equipment today for a New Tplink Omada system.

Give it another try if you’ve had problems.

Thank you for the guide.

Reply
Basti on December 25, 2023 at 7:33 pm
Hi i not can download have a error.
```
W: Fehlschlag beim Holen von https://www.ui.com/downloads/unifi/debian/dists/stable/InRelease Verbindung mit dl.ui.com:443 nicht möglich (52.222.253.173) - connect (113: Keine Route zum Zielrechner)
W: Einige Indexdateien konnten nicht heruntergeladen werden. Sie wurden ignoriert oder alte an ihrer Stelle benutzt
```
Reply
1. Emmet on December 25, 2023 at 8:09 pm
  
  Editor
  
  Hi Basti,
  
  It looks like your internet connection is having issues connecting to Ubiquiti’s repository. I quickly tested this locally and am not facing the same connection error.
  
  A couple of things you could try. First is to try using a different DNS provider such as Cloudflare (1.1.1.1) or Google DNS.
  
  Alternatively, if that still doesn’t work you could attempt to use a VPN.
  
  Kind regards,
  Emmet
2. Basti on December 25, 2023 at 10:19 pm
  
  Unfortunately it doesn’t work either 🙁 At first I thought it could also be due to PIHole, but I also identified it without success
Darren McGrandle on November 30, 2023 at 10:37 am

Just checking in – I installed on Bookworm using a brand new 64bit install, and all the steps in this guide worked flawlessly. I used the “lite” version since I am running the Pi headless and don’t need a desktop. Thanks for a straightforward guide.

Reply
1. Mathias on December 5, 2023 at 10:54 pm
  
  Worked for me. Thanks a lot.
Mike on November 30, 2023 at 12:57 am
First off, thank you for putting together and maintaining this guide. It is fantastic.

I am trying to update Unifi, but it thinks it is already at the latest version. Looking at the list of packages, I suspect I tangled myself up somehow as the package has the version listed. I can only guess that I made it 7.4 specific somehow. Any feedback would be greatly appreciated.
```
$ sudo apt update
Hit:1 http://security.debian.org/debian-security bullseye-security InRelease
Hit:2 http://deb.debian.org/debian bullseye InRelease                          
Hit:3 http://deb.debian.org/debian bullseye-updates InRelease                  
Hit:4 https://linux.teamviewer.com/deb stable InRelease                        
Hit:6 http://archive.raspberrypi.org/debian bullseye InRelease                 
Hit:5 https://dl.ui.com/unifi/debian unifi-7.4 InRelease
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
All packages are up to date.
```
Reply
1. Emmet on December 1, 2023 at 1:08 am
  
  Editor
  Hi Mike,
  
  Sorry to see that you are having issues updating Unifi.
  
  My thought immediately goes to you potentially completing this tutorial when we had a different workaround in place. This workaround was pinning UniFi to the older release repository.
  
  You should be able to just update to the new line where we tell the repository to grab the X64 version of the repository (Unifi is written in Java, so for now we can continue to run the software regardless of what their repo claims.
  
  Just run the following command.
  
  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
  
  And then re-run a “sudo apt update” and “sudo apt upgrade”.
  
  Please let me know if this resolves the issue you are running into.
  
  Kind regards,
  Emmet
Michael on November 29, 2023 at 6:43 am

Hi there.
Do I need to run a specific version of raspbian, to get this to work?
I’m running Bullseye, and I get a lot of errors, while trying to follow your tutorial.

pi@ubntcontroller:~ $ sudo dpkg -i libssl1.0.deb
dpkg: error processing archive libssl1.0.deb (–install):
package architecture (arm64) does not match system (armhf)
Errors were encountered while processing:
libssl1.0.deb

pi@ubntcontroller:~ $ sudo dpkg -i mongodb.deb
dpkg: error processing archive mongodb.deb (–install):
package architecture (arm64) does not match system (armhf)
Errors were encountered while processing:
mongodb.deb

Hope to hear from you.

Reply
1. Emmet on November 29, 2023 at 9:44 am
  
  Editor
  
  Hi Michael,
  
  As mentioned at the start of the tutorial, you must be running a 64-bit (ARM64) version of Raspberry Pi OS for this tutorial to work.
  
  You are currently running a 32-bit (armhf) version.
  
  Kind Regards,
  Emmet
Dupie on November 22, 2023 at 8:20 am

Thank you very much for this
I am a farmer and an idiot at this! Every step goes great, cannot resolve ip address in browser, browser instead searches web for hits (step 2 of “first boot”).
Help please and use small words.
Much appreciated.

Reply
1. Emmet on November 22, 2023 at 12:39 pm
  
  Editor
  Hi Dupie,
  
  Sorry to hear that you are running into issues with connecting to the UniFi controller.
  
  First, ensure you are connecting to your Pi’s IP address when typing in the URL. For example, our IP for our Pi is 192.168.0.134 so we would use the URL “https://192.168.0.134:8443“.
  
  If that doesn’t work, try checking the status of the “unifi” service by using the following command.
  
  sudo systemctl status unifi
  
  If everything is working properly, you should see something like “Active: active (running)“.
  
  Kind Regards,
  Emmet
2. Dupie on November 22, 2023 at 10:55 pm
  
  Thank you for the speedy reply Emmet. This solved my problem, cause I did not remove the [..] brackets when I entered the IP address. I laughed at myself too.
Melen on November 22, 2023 at 1:18 am

Hi.
Thank you for this easy-to-follow-guide.

Big up!

Reply
Veejaymat on November 17, 2023 at 3:09 pm

The install process fails for me on step 8, with the following error

pi@raspiserv:~ $ sudo dpkg -i libssl1.0.deb
dpkg: error processing archive libssl1.0.deb (–install):
package architecture (arm64) does not match system (armhf)
Errors were encountered while processing:
libssl1.0.deb

Raspi 3B; running Bullseye

Reply
1. Emmet on November 17, 2023 at 4:19 pm
  
  Editor
  
  Hi Veejaymat,
  
  As mentioned at the start of the tutorial, you must be running a 64-bit version of Raspberry Pi OS. You are using an “armhf” system which is 32-bit.
  
  Kind regards,
  Emmet
2. Jason on November 21, 2023 at 2:30 am
  Very weird… I have a 64bit version installed – yet when I run sudo apt update it gives me the following message:
  
  N: Skipping acquire of configured file 'ubiquiti/binary-armhf/Packages' as repository 'https://www.ui.com/downloads/unifi/debian stable InRelease' doesn't support architecture 'armhf'
  
  When I check if I am running 64 bit – it shows this:
  
  getconf LONG_BIT 64
  
  uname -m aarch64
  
  This is my version:
  
  cat /etc/os-release PRETTY_NAME="Debian GNU/Linux 11 (bullseye)" NAME="Debian GNU/Linux" VERSION_ID="11" VERSION="11 (bullseye)" VERSION_CODENAME=bullseye ID=debian HOME_URL="https://www.debian.org/" SUPPORT_URL="https://www.debian.org/support" BUG_REPORT_URL="https://bugs.debian.org/"
  
  THANKS SO MUCH – YOU’RE THE BEST!
3. Emmet on November 21, 2023 at 8:35 pm
  
  Editor
  Hi Jason,
  
  Sorry to hear that you are having issues.
  
  If you ran this tutorial previously, you will need to update the source file. We have to force the arch to “amd64” to get it to download newer releases from the repository.
  
  You should hopefully be able to fix this by using the following command.
  
  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
  
  Please let me know if this resolves the issue for you.
  
  Kind Regards,
  Emmet
4. Jason on November 27, 2023 at 12:36 am
  
  You’re an absolute boss! Thanks so much for this. After using that command I could run the usual sudo apt update / upgrade route and I updated from Network 7.4.162 to Network 8.0.7.
  
  Thanks a lot!
Dave B on November 16, 2023 at 11:22 am

I’ve used this method in the past for setting up a PI 3 to run UniFi controller. I’ve just tried to reconfigure on one of my PI s (corrupt memory card) and this method doesn’t seem to work for me any more, I get to the 88% when installing.
Is there a work-around to perhaps use an earlier version of the setup to get this to run?

Reply
1. Emmet on November 18, 2023 at 12:36 am
  
  Editor
  
  Hi Dave,
  
  The main thing I would recommend is trying Raspberry Pi OS Bullseye. For some reason Bookworm seems to be causing some weird issues, I’ve managed to successfully install it but others are still reporting issues.
  
  Kind Regards,
  Emmet
Eric on November 15, 2023 at 11:51 pm

Anyone got it works on raspberry 3B 1G ram?
I got it to the step:
sudo apt install openjdk-17-jre-headless unifi
Stucked at 88% and the whole system freeze
Task manager shows 774MB of 908MB used, not sure if thats the issue?

Reply
1. Emmet on November 16, 2023 at 2:23 am
  
  Editor
  
  Hi Eric,
  
  While you should still be able to install OpenJDK 17, you will definitely run into issues if you did manage to install UniFi Controller. They recommend a minimum of 2GB of RAM.
  
  ~~EDIT: It appears there might be something going on weird with Bookworm on UniFi. Try using Buster in the mean time.~~
  EDIT2: Testing the tutorial again on a clean installation of Raspberry Pi OS 64-bit Bookworm, everything does seem to be working. Installation seems to take a bit longer than I remember it, but it does work.
  
  I tested this on a Raspberry Pi 400 so that has 4GB of RAM.
  
  Kind Regards,
  Emmet
2. Volker on November 16, 2023 at 10:28 pm
  
  Hi Eric,
  I had also problems at the same step.
  I have a raspberry Pi 4. I had the problems with the newest OS.
  
  With Raspberry Pi OS Bullseye 64-bit It runs.
3. Emmet on November 18, 2023 at 12:41 am
  
  Editor
  Hi Volker,
  
  I have successfully installed Unifi on to Raspberry Pi OS Bookworm 64-bit. So I’m not completely sure what is going wrong here.
  
  The first time I tried with a non-clean system everything broke and it refused to install. But a clean install worked fine.
  
  If someone is having issues with it getting stuck during setup, could you see if it has attempted to start up the UniFi service, and if there is anything in the logs if it does give a response.
  
  You can check the status of the Unifi servce by running the following command.
  
  sudo systemctl status unifi
  
  Kind Regards,
  Emmet
b0bz0r on November 13, 2023 at 1:22 am

Thanks for the great tutorial.
Installed it on a Raspberry Pi 5, and it runs super smooth!

Reply
Zhi Ming on November 4, 2023 at 8:46 pm

This updated guide (4th Oct 2023) is superb! I followed the steps on the latest version of Raspberry Pi OS (Bookworm) on my RPi 4B, everything runs like clockwork.

One thing to note from my experience and already reminded at the top of the article is to use only the 64 bit version of the OS. Otherwise you will get an libc error when trying to install LibSSL 1.0.

Hello from Singapore and thank you Emmet, I hope you will continue to keep this article updated. It helps many folks round the globe.

Reply
1. Matej on November 10, 2023 at 10:10 am
  
  Thanks a lot, installation went smoothly with 64bit OS.
Graham on November 1, 2023 at 8:11 am

Thank you so much! It just worked, straight up first time!! Much appreciated.

Reply
Maynard on October 16, 2023 at 9:25 am

Thx Emmet
Updated to 7.5 without issue
Much appreciated

Reply
Bartwick on October 12, 2023 at 12:43 am

Thank you! From the image, it looks like firmware 7.5 is being installed now? I used this a few months back and it’s been flawless but at the time 7.4 was the latest firmware. Could you please provide update instructions?

Reply
1. Emmet on October 12, 2023 at 1:35 pm
  
  Editor
  
  Hi Bartwick,
  
  As long as you are running a 64-bit operating system, you should be able to follow the first few steps under the “Installing the UniFi Controller to the Raspberry Pi” section.
  
  At step 4, you will want to run “sudo apt install openjdp-17-jre-headless“, and then after that run “sudo apt upgrade -y“.
  
  Hopefully that should update your safely from Unifi 7.4 to 7.5. Just ensure you make a backup before following these steps.
  
  Cheers,
  Emmet
Blazej on October 7, 2023 at 9:41 pm

Great job!
Thank you

Reply
Jens on October 4, 2023 at 6:37 am

Thanks Emmet! Followed step-by-step and everything worked fine.

Reply