Installing the UniFi Controller on the Raspberry Pi

by Emmet

Updated Apr 08, 2024

If you buy through our links, we may earn an affiliate commission. Learn More.

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

Raspberry Pi Case ( Amazon )
USB Keyboard ( Amazon )
USB Mouse ( Amazon )
HDMI Cable ( Amazon )

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.

191 Comments

Michal on October 7, 2022 at 11:52 am

Saved my day. UniFi controller crashed on my Raspberry pi 3. I had a guide that I followed last time but didn’t know mongodp is no longer installable on new release of pi.
I found this tutorial and it worked well from start to finish.
I also extracted autobackup files from my crashed UniFi and was able to restore my settings.
THANKS!!!!!

Reply
Paul Bulckens on September 26, 2022 at 2:59 pm

Fantastic and clear installation guide. Thank you. Paul (Belgium)

Reply
Isaac on August 21, 2022 at 12:34 am

Excellent and very well guided tutorial, I’m not Linux expert and I could even made it work! Thanks

Reply
RichardH on June 27, 2022 at 11:43 pm

For everyone’s information, this works very well, but only on a 32 bit Pi!

Reply
TechGuy on May 31, 2022 at 5:18 pm

A clear and concise guide 👍
It worked for me on the 1st try!
Raspberry Pi 3b+

Reply
Alex on March 13, 2022 at 8:41 am

unifi doesn’t start on restart. How do I make it automatically run on system start? Thanks!

Reply
1. Emmet on March 14, 2022 at 1:26 am
  
  Editor
  Hi Alex,
  
  Can you try running the following command, I don’t currently have the UniFi controller installed so can’t test this at the moment.
  
  sudo systemctl enable unifi
  
  Additionally, you should be able to get the status of the service by running the command below. This should let us know whether the service has been enabled
  
  sudo systemctl status unifi
  
  Cheers,
  Emmet
  
  Reply
Baks on March 11, 2022 at 10:31 am

Hi,
thanks for great tutorial.
I have just tried it but the unifi does not want to start.
It shows itself as active but there is a problem during start.

Mar 11 00:19:37 netcontrol systemd[1]: Starting unifi…
Mar 11 00:20:40 netcontrol unifi[424]: WARN Unable to load properties from ‘/usr/lib/unifi/data/system.properties’ – /usr/lib/unifi/data/system.properties (No such file or directory)
Mar 11 00:21:31 netcontrol unifi.init[343]: Starting Ubiquiti UniFi Network application: unifi
Mar 11 00:21:31 netcontrol unifi.init[698]: failed!
Mar 11 00:21:31 netcontrol systemd[1]: Started unifi.

Can someone help with that?

Reply
1. Emmet on March 14, 2022 at 4:29 pm
  
  Editor
  
  Hi Baks,
  
  Looking into it, that particular error seems to be caused by a variety of different issues.
  
  Do you have a firewall enabled on your Raspberry Pi?
  
  Cheers,
  Emmet
  
  Reply
2. John on March 31, 2022 at 10:59 am
  
  I saw that WARN on first load and then I just stopped and started the service. I think it gets created on first boot.
  
  Reply
Horia on February 23, 2022 at 2:53 am

Very useful tutorial, couldn’t have done it without this. Thank you so much!

Reply
Matt on January 23, 2022 at 10:59 am
For some reason when you click the “copy” button next to the string:
```
 
curl https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee /usr/share/keyrings/ubiquiti-archive-keyring.gpg >/dev/null 
```
And then paste it, the output is this:
```
 
curl https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee /usr/share/keyrings/ubiquiti-archive-keyring.gpg >/dev/null 
```
Just giving you a heads up since it can mess you up if you aren’t paying attention.

Reply
1. Matt on January 23, 2022 at 11:05 am
  
  For some reason when I posted my comment is stripped the character change. But either way when you copy the string the “>” character is copied as it’s html character tag “& gt;” (minus the space between the & and g)
  
  Reply
2. Emmet on January 23, 2022 at 10:18 pm
  
  Editor
  
  Hi Matt,
  
  Thank you very much for pointing this out. I have updated the script that handles the copying so that html elements are properly handled.
  
  Cheers,
  Emmet
  
  Reply
Jorg on January 8, 2022 at 11:11 am

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

Cheers, Jorg.

Reply
Carsten Kochems on December 29, 2021 at 7:51 am

Only this Tutorial works, great 🙂

Reply
Wannes on December 2, 2021 at 2:10 am

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

Reply
ErshN8D on November 12, 2021 at 9:52 am

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

Reply

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.

Emmet on November 18, 2021 at 3:48 pm

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

Reply

Martin on November 9, 2021 at 11:49 pm

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.

Reply
1. Emmet on November 18, 2021 at 3:45 pm
  
  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
  
  Reply
2. Emmet on November 22, 2021 at 10:30 pm
  
  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
  
  Reply
Etienne on October 20, 2021 at 5:35 am

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

Reply
1. Emmet on October 23, 2021 at 10:56 pm
  
  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
  
  Reply
Louis Apostolakis on August 24, 2021 at 12:55 am

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?

Reply
1. Emmet on August 24, 2021 at 10:06 pm
  
  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
  
  Reply
Stephanie on August 8, 2021 at 4:21 am

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

Reply
1. Emmet on August 9, 2021 at 2:49 am
  
  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
  
  Reply
Thankful Dan on July 22, 2021 at 7:53 am

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.

Reply
Kaden on June 14, 2021 at 5:52 pm

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?

Reply
1. Emmet on June 14, 2021 at 8:22 pm
  
  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
  
  Reply
2. John on March 31, 2022 at 10:54 am
  
  I hit this because I had missed “sudo apt install openjdk-8-jre-headless”
  
  Reply