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

Kaveh on October 4, 2023 at 4:05 am

Amazing! Thank you for this writeup.

Reply
Trekker4Life on October 4, 2023 at 3:32 am

I’m lucky I found THESE instructions (updated OCT 3rd) before any others; they’re excellent! Thank you! Previously, the only way I could get the UNIFI controller to work on my Raspberry Pi 4b was by installing the Ubuntu OS. It worked for approx. 6 months until I tried to upgrade the controller software to 7.5.176 last week… then it crashed my Raspberry Pi. I always wanted to install it on the Raspberry Pi OS (lite), so I installed the 64-bit version as youse directed, followed these instructions, and bingo. I was successful this time, and it’s much faster than before. I think I will just stick to pimylifeup.com for any future reference I might need. Thanks again.

Reply
Roedie on September 29, 2023 at 6:45 am

Hi Emmet,

Thank you for posting this info.
Worked first time following your steps!

Cheers,
Roedie

Reply
Rob on September 18, 2023 at 11:54 pm
Hi,

It looks like the 7.4 branch may no longer exist; or maybe there’s another issue:
```
Err:5 https://dl-origin.ubnt.com/unifi/debian unifi-7.4 InRelease              
  Could not connect to dl-origin.ubnt.com:443 (3.81.31.48), connection timed out
......
W: Failed to fetch https://www.ui.com/downloads/unifi/debian/dists/unifi-7.4/InRelease  Could not connect to dl-origin.ubnt.com:443 (3.81.31.48), connection timed out
```
Is there an update on the location or other troubleshooting steps to connect to that version? Using the default URL (https://dl.ui.com/unifi/debian stable InRelease) connects but gives the aforementioned “unsupported architecture” error.

Reply
1. Emmet on September 20, 2023 at 12:14 am
  
  Editor
  
  Hi Rob,
  
  It looks like Unifi may have been having issues earlier in the day. I just tested it then and everything seemed to work properly.
  
  Please let me know if you are still running into issues.
  
  Cheers,
  Emmet
Marcel S on September 8, 2023 at 5:11 pm

Is this working with Raspberry Pi 4?
I have unfortunately not found a proper tutorial for the Pi 4
According to many articles there are also problems with the 64 bit architecture.
Can anyone confirm this?

Does anyone have the console running on the Pi 4?

Reply
1. Emmet on September 9, 2023 at 12:44 am
  
  Editor
  
  Hi Marcel,
  
  Last time I tested it this tutorial worked fine on the Raspberry Pi 4, and you now actually require a 64-bit system to get the UniFi controller to work on the Pi.
  
  Cheers,
  Emmet
Karl on September 7, 2023 at 5:16 pm
Hi,
I used this guide when I installed the unifi controller. Now when I want to upgrade the controller to the latest release I get this message…
```
sudo apt update
[SNIPPED]
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'
```
Reply
1. Emmet on September 7, 2023 at 8:03 pm
  
  Editor
  Hi Karl,
  
  Unfortunately there seems to be an issue with getting Unifi controller 7.5+ installed at the moment. You can lock the package list to the working 7.4 branch by using the following command.
  
  echo 'deb [arch=armhf signed-by=/usr/share/keyrings/ubiquiti-archive-keyring.gpg] https://www.ui.com/downloads/unifi/debian unifi-7.4 ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list
  
  Will try and look into this further.
  
  Cheers,
  Emmet
2. eze on October 3, 2023 at 1:13 pm
  you can also change to the amd64 repository
  
  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/unifi.list
3. Gus on October 3, 2023 at 9:56 pm
  
  Editor
  
  Hi eze,
  
  Thank you for pointing this out. I have updated the tutorial to now just use the amd64 repository.
  
  It is strange that they removed “armhf” or “arm64” from the supported list even though they serve the same package for all architectures.
  
  Cheers,
  Emmet
4. Karl on October 3, 2023 at 5:16 pm
  
  Hi again,
  
  This fix will let you upgrade from 7.4 to 7.5.
  
  Edit the source file
  
  To
  
  deb [arch=amd64…
  
  From
  
  deb [arch=armhf
5. Gus on October 3, 2023 at 9:57 pm
  
  Editor
  
  Hi Karl,
  
  Thank you for mentioning this. I have updated the guide to refer back to the “stable” release again and have updated it to reference the “amd64” architecture since it still serves an ARM compatible package.
  
  Hopefully they don’t make any breaking changes like that again, or at least add “arm64″/”armhf” back to the supported architectures for the repository.
  
  Cheers,
  Emmet
Tim on September 5, 2023 at 3:48 pm

Hi Guys,
Thank you so much for this tutorial, it has worked perfectly….
Until the last update.
Unfortunately my pi became unresponsive and after reinstalling with pi OS 64 lite I cannot get Unifi to install.
I’m not a pi expert so am a little lost but it would seem that the repository or something similar has been changed by unifi?
Any tips would be great.
Thank You!!

Reply
1. Emmet on September 5, 2023 at 9:03 pm
  
  Editor
  
  Hi Tim,
  
  Looks like the Unifi repository isn’t providing a release for “7.5” for the Pi’s hardware for some reason. I have temporarily worked around this by changing the release from “stable” to “unifi-7.4”.
  
  Please try following the steps again.
  
  Cheers,
  Emmet
2. Ivar on September 6, 2023 at 6:15 am
  
  I had the same issue, but the change worked! Thanks Emmet
Jason on July 30, 2023 at 3:34 am

Thanks so much! Very easy and worked well!

Reply
Jason on July 28, 2023 at 8:48 pm

Hi all,

How would I go about updating to the latest version of the unifi controller after everything is set up and running?

Cheers

Reply
1. Emmet on July 29, 2023 at 11:25 pm
  
  Editor
  
  Hi Jason,
  
  Updates should be provided through the official Unifi package repository.
  
  To update you should only need to run “sudo apt update” followed by “sudo apt upgrade“.
  
  Cheers,
  Emmet
Steve on July 2, 2023 at 6:52 am

Amazingly helpful. I never have setup instructions work okay at all.

These instructions were flawless.

Thank you!

Reply
Rolando Barberis on June 30, 2023 at 1:49 am

Thank you for posting this info. Worked first time following your steps!

Reply
dsm52 on June 16, 2023 at 12:37 am

Hi Emmet,

Thanks for this tutorial. It’ll be excellent timing for lots of pi unifi users as of v7.4.156 of the unifi controller requires 64-bit OS and will be migrating.

I took a backup from v7.3.83 and then followed your instructions with Rasbian 64-bit bullseye (lite) and all working like a charm on a pi 4 4GB, restoring from backup as soon as the unifi web controller came up. A couple of notes from my experience:

Unifi controller didn’t like me changing the IP address of the pi post-install (web page doesn’t load). So I just reinstalled unifi (“sudo apt remove unifi”, followed by “sudo apt install unifi”) which did the trick.

After about 30mins uptime, reported load (via “top”) is around 3.5 which seems a little high (I can’t recall what it was on 32-bit raspbian).

I much prefer your method of installing (adding unifi respositories) as upgrading now should just be a matter of “sudo apt update” and “sudo apt upgrade” (is that right?) rather than relying on community installation scripts.

For others information, I run both unifi and pi-hole on my pi.

Thanks again

Reply
1. Emmet on June 16, 2023 at 1:03 am
  
  Editor
  
  Hi dsm52,
  
  I am glad this tutorial worked out for you and thank you for providing notes from any issues you ran into. Hopefully that will help others in the future who run into the same issue.
  
  Yes, you should be able to just continue to update by using “sudo apt update” and “sudo apt upgrade” as long as they don’t introduce any big breaking changes again.
  
  Cheers,
  Emmet
sennai on June 14, 2023 at 5:54 am

Thanks again for this excellent instructions. Migrated from 32bit RPi to 64bit. Borrowed a RPi 4B 8gb from my friend as a second instance, installed the OS, then followed your instructions for Unifi Network Application 7.4.156, then restored the backup from 7.3.83, stopped the unifi service on the first instance, all the devices got adopted immediately on the second instance without a glitch. Will switch the OS ssd from the borrowed RPi to my RPi.
Cheers.

Reply
Douglas on June 8, 2023 at 11:05 am

Hey Emmet, thanks for the update. I arrived here because the latest Unifi release broke my setup, and I was able to utilize this guide to start over again. For anyone reading, here are the steps I took to exfiltrate my backups and get my controller going again. I had a 32bit RPI OS install, ended up on Ubuntu Server 64bit. Perhaps one could update to 64bit RPI OS in place, but starting from scratch is easy, and my Raspberry Pi had no purpose other than to host Unifi. If you’re running other services, perhaps starting from scratch isn’t for you!

Process #1 – Exfiltrate Unifi backups
1a. Add the ‘pi‘ user to the ‘unifi‘ group, so it can access where the backups are stored. SSH into the pi, and run the following command without the quotes: “usermod -a -G unifi pi”
1b. Get your backups out. I ran the following on my Macbook, adapt as necessary to your needs: “scp -r pi@192.168.10.50:/usr/lib/unifi/data/backup/autobackup/ /Users/macbook/”

Process #2 – Install a fresh copy of a 64-bit version of Linux
NOTE: I first tried RPI OS 64bit, but after restoring my Unifi backup, it would freeze/brick the Pi at a certain point in the Unifi startup process (or maybe I was too impatient?) It would respond to pings, but I could not SSH in, my open SSH session viewing HTOP would freeze, etc. I did not investigate or diagnose whatsoever, I just moved on to Ubuntu Server 64bit where I had no such problems. Your mileage may very
2a. There are many ways to do this, but I started by installing the official Raspberry Pi Imager
2b. Go into the advanced options, enable SSH, and prefill your username/password
2c. Select a 64 bit OS of your choice, I chose Ubuntu Server 23.04
2d. Flash to your SD card (or in my case USB stick)
2e. Install storage in Raspberry Pi, boot it up

Process #3 – Follow PiMyLifeUp’s instructions
3a. Go read and follow the blog post above. When accessing the web user interface for the first time, restore your latest backup
3b. While restoring the backup, depending on what Pi model you’re using… be very patient. It took ~20 minutes on my 3B+ with 1GB. I tried a restore on a fresh Pi 4 with 8GB ram and it took a fraction of the time, maybe 2 minutes.

Cheers everyone

Reply
1. Douglas on June 9, 2023 at 10:18 am
  
  Just wanted to follow up on this post with more anecdotal experience.
  
  I do not recommend running the latest Unifi Controller 7.4.156 on a Raspberry Pi 3b+ with 1GB RAM. I don’t know if a Pi 4 with 1GB would fare better. My experience on both Ubuntu Server and Raspberry Pi OS is that once loaded up with clients and devices (for me, ~15 clients and 6 devices) the memory needs too far exceed 1GB, leading to long system hangs.
  
  I’m now set up on a Pi 4 with 8GB ram without issue. Memory usage observed in htop hangs around ~1.6GB.
  
  System requirements at the following link (FAQ #7 as of this writing, What are the UniFi Network application system requirements?) say 2GB minimum. My experience bears this out.
  https://help.ui.com/hc/en-us/articles/360012282453
Martin on June 4, 2023 at 12:46 am

Hi! thanks for htis awesome tutorial, I’ve been runnning on it for months now. Is there a risk in updating my current installation on raspberry pi os 64 bits? Should I clean it up and start from scratch?

Reply
1. Emmet on June 4, 2023 at 11:41 am
  
  Editor
  
  Hi Martin,
  
  There is always going to be a risk when you make such a big change to the operating system. While you can technically run 64-bit OS alongside 32-bit it can be problematic ensuring you have all the 64-bit versions you need installed.
  
  The easiest path in my opinion would be to backup your UniFi configuration, then start from scratch on a fresh Raspberry Pi OS 64-bit installation. On the bright side, there hopefully shouldn’t be another huge drastic change that would require you to start over.
  
  Cheers,
  Emmet
Jason on June 3, 2023 at 6:05 pm

Just wanna say you’re an absolute legend and the new script works amazingly on my new Pi. Thanks a million man – got a donation link?
I’m only using my Pi as a Unifi controller – so I was wondering if you have any tips for power consumption? Could I theoretically install your script on the lite version of 64bit Raspberry OS? I think that might use even less energy, right? Currently I’m just letting it run on the desktop version and pull out off the accessories after setup.

Reply
1. Emmet on June 3, 2023 at 7:02 pm
  
  Editor
  
  Hi Jason,
  
  Really glad to hear that it has all worked out for you! Always a huge relief when a tutorial works fine for others. We don’t have a donation link but we do offer an ad-free subscription.
  
  The Raspberry Pi isn’t super power hungry to begin with, but using Raspberry Pi OS Lite might help a little since it has significantly less packages/software set up on it from the get-go. The guide will work perfectly on the lite version of Raspberry Pi OS and that is how I typically test it out.
  
  Cheers,
  Emmet
Louis on June 3, 2023 at 5:10 am

Will this new method work with the Raspberry Pi 3B which only has 1GB of ram or does 64 but OS/ Unifi Controller 7.4/ MongoDB 3.6 require more ram than that if so can you create a ram pool in the SD card?

Reply
1. Emmet on June 3, 2023 at 9:26 am
  
  Editor
  
  Hi Louis,
  
  The Unifi Controller should continue to work on your Raspberry Pi 3B even if it only has 1 GB of RAM. While there is a slight increase in RAM consumption moving from a 32-bit to 64-bit system it shouldn’t be large enough to make it unusable.
  
  You can increase the size of the swap file to reduce the chance of running into out-of-memory errors. But please note that the swap is significantly slower than RAM.
  
  Cheers,
  Emmet
2. Pasci on November 30, 2023 at 8:45 am
  
  After memory issues every 2-3 days with Raspberry Pi 3B / 1 GB RAM. I increased swap file to 1500 (1.5GB) this will reduce life of SD-Card but my memory issue is solved 😉
Ramzez on June 3, 2023 at 1:46 am

hi @Emmet thank you for the prompt reply. I am pretty sure I have 64bit system installed by running `uname -m` gives me `Linux raspberrypi 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr 3 17:24:16 BST 2023 aarch64 GNU/Linux` however when I try to install arm64 packages I get an error “`package architecture (arm64) does not match system (armhf)
“`

Reply
1. Emmet on June 3, 2023 at 1:59 am
  
  Editor
  Hi Ramzez,
  
  That error message would indicate that you are running a 32-bit release of Raspberry Pi OS so that is a little string.
  
  If you run the following command within the terminal, what do you see?
  
  dpkg-architecture -q DEB_BUILD_ARCH
  
  You should see “arm64” if you are running the 64-bit flavor of Raspberry Pi OS.
  
  Cheers,
  Emmet
Jason on June 3, 2023 at 1:42 am

Thanks so much! I was just in the middle of using the old one haha…
Will try to change my os to 64bit now… Any quick suggestions on how to do this?
Thanks so much!

Reply
1. Emmet on June 3, 2023 at 2:00 am
  
  Editor
  
  Hi Jason,
  
  The cleanest / quickest way to do this is to just flash the 64-bit version of Raspberry Pi OS instead of the 32-bit one.
  
  Cheers,
  Emmet

Hi,

I thank you for this tutorial.
I was able to install Unifi a few weeks ago without any problems. I’ve just tried again this morning but I get an error at the last stage (97%).

[LOGS SNIPPED]
Jun 02 10:08:43 raspberrypi java[2756]: WARNING: An illegal reflective access operation has occurred
Jun 02 10:08:43 raspberrypi java[2756]: WARNING: Illegal reflective access by org.apache.catalina.loader.WebappClassLoaderBase (file:/usr/lib/unifi/lib/tomcat-embed-core-9.0.65.jar) to field java.io.Obj>
Jun 02 10:08:43 raspberrypi java[2756]: WARNING: Please consider reporting this to the maintainers of org.apache.catalina.loader.WebappClassLoaderBase
Jun 02 10:08:43 raspberrypi java[2756]: WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
Jun 02 10:08:43 raspberrypi java[2756]: WARNING: All illegal access operations will be denied in a future release

Could you help me ?

Thanks

Emmet on June 3, 2023 at 1:53 am

Editor

Hi Eric,

It looks like the Unifi team pushed a release that broke how the original tutorial worked. I have updated the tutorial to work now but you will need to be running a 64-bit operating system on your Raspberry Pi.

Please try the updated tutorial and let me know whether you are still running into issues.

Cheers,
Emmet