Running UniFi Network Controller on a Raspberry Pi 3B+, Debian Bookworm 64-bit in 2025

Smith6612
Raspberry Pi 3B+ Computer with the Raspbian and UniFi Network logos

Yep. The title is one of those that necessitates the 2025 marker. I had some trouble getting the latest version of the UniFi Controller running on a Raspberry Pi 3B+, which has been hosting my UniFi Network Controller for about a decade now, but underwent a replacement of the Operating System image. A lot of the information on the Internet is somewhat outdated, or very hodgepodge, and I wanted to share what worked for me.

To start, I installed the latest version of the Raspberry Pi OS (formerly Raspbian) to the Raspberry Pi, replacing Ubuntu Server 24.04, since I wanted something a bit more lightweight in RAM usage out of the box, and I was encountering some troublesome lock-up problems with the Ubuntu installation, likely caused by many years of in-place upgrades and configurations I have long forgotten about. The machine would stop responding on SSH, stop pinging on the network, and wouldn’t output on video when it would lock up. So alright, tough to debug problem. As of this post, the latest version of the Raspberry Pi (Raspbian) OS is built on Debian 12 (Bookworm). For the sake of my Pi, as I don’t need a Desktop environment on it, I used the Raspberry Pi OS Lite (64-bit) image.

From past experience, selecting the 64-bit version of Linux is very important, as MongoDB has database size limits which UniFI routinely bumps up against, no matter how much you try to avoid it. The database size on MongoDB is limited to 2GB when running a 32-bit copy of MongoDB. Once the database hits 2GB, UniFi is no longer able to record statistics, and on the next restart, won’t restart properly. This is the problem which plagued the original UniFi CloudKey (UCK) and corrupted databases, requiring the Statistics database to be purged, if you were lucky to catch the problem in time. Most of the time you’d have to prune back the database manually (usually by deleting the ace.stats database files manually) then manually perform a repair, as MongoDB and the Ubiquiti Repair Scripts wouldn’t be able to access the database otherwise. We need to run a 64-bit OS and a 64-bit copy of MongoDB, despite the Raspberry Pi 3B+ having 1GB of RAM, as the 2GB limit is with the Storage engine.

With a copy of Raspberry Pi OS 12 Lite (64-bit) imaged onto an SD Card and loaded into the Raspberry Pi, the next steps are to install the packages we need. Most importantly, we need a very specific version of MongoDB, MongoDB 4.4.1. The reason for this specific version is because of the processor installed into the Raspberry Pi 3B+. If we attempt to install any newer version of MongoDB, or even certain older versions of MongoDB, the UniFi Controller will never complete the initial installation. This is because under the hood, when UniFi Network launches and calls for MongoDB, the Database engine will start, then immediately crash with Error -132. Error 132 means “Illegal Instruction”, and this translates to the processor not having support for specific CPU instructions that MongoDB is calling for. MongoDB 4.4.1 is a version which specifically has targeting in it for older processor architectures. This also resolves issues in the future, once UniFi Network requires a MongoDB version newer than 3.6, by running a newer version of MongoDB. Otherwise, the upgrade process is a painful version-by-version installation procedure that I’ve personally had problems with on the Raspberry Pi due to Error -132.

Here’s how to install MongoDB 4.4.1 and UniFi on the system.

  1. Assuming you have a fresh install of Raspberry Pi OS, update your System.
    • sudo apt update && sudo apt upgrade -y && sudo apt autoremove

      This command will update the APT Package Manager’s repository cache. Afterwards, it will perform an upgrade of all packages with updates available, and automatically accept any prompts with a “yes.” Finally, because some packages may be no longer needed following an upgrade, we let APT remove unused dependency packages.
  2. Add the UniFi Repository to APT. Follow only steps 1-3 for now! Otherwise you may be in a world of hurt later.
  3. Next, add the MongoDB Repository to APT. Run each command listed below.
    1. curl -fsSL https://www.mongodb.org/static/pgp/server-4.4.asc | \
      sudo gpg -o /usr/share/keyrings/mongodb-server-4.4.gpg \
      --dearmor

      This command adds the MongoDB PGP Public Key into the Keyring, which is needed to authenticate the APT Repository.
    2. echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-4.4.gpg arch=arm64] http://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

      This command adds the MongoDB 4.4 Repository to our APT Sources list. Note that we are pointing to the Ubuntu-specific repository and not the Debian-specific repository. This is because Mongo does not have ARM64 builds of MongoDB Server available in the Debian-specific Repository as of this writing. Instead, we can use Ubuntu’s Mongo repository, given Ubuntu is downstream of Debian. This command also tells APT to only focus on arm64 (64-bit) packages, as we do not want it looking for 32-bit packages or digesting information for an x86 processor. Finally, this command tells APT what Public Key to use, specifically, the key downloaded in Step 3.1 above, so we can actually download from the Repository. We are targeting Ubuntu Focal (20.04 LTS) because this is the latest version of Ubuntu, with an ARM64 version of MongoDB Server 4.4.1 in the Repository that I could locate.
  4. Next, we need to install MongoDB Server 4.4.1 manually.
    1. sudo apt update

      Since the APT Repository list was updated, APT’s caches need to refresh so it can learn about the MongoDB Server package. If any error occurs in this step, the problem is likely caused by something in Step 3 above being outdated or entered incorrectly.
    2. sudo apt-get install -y mongodb-org=4.4.1 mongodb-org-server=4.4.1 mongodb-org-shell=4.4.1 mongodb-org-mongos=4.4.1 mongodb-org-tools=4.4.1

      This command installs the exact version of MongoDB Server needed, along with the specific tools MongoDB Server will need to run. Assuming all other steps have been completed successfully, and Mongo hasn’t modified their repositories, all of these packages should download without an issue.
    3. echo "mongodb-org hold" | sudo dpkg --set-selections && echo "mongodb-org-server hold" | sudo dpkg --set-selections && echo "mongodb-org-shell hold" | sudo dpkg --set-selections && echo "mongodb-org-mongos hold" | sudo dpkg --set-selections && echo "mongodb-org-tools hold" | sudo dpkg --set-selections

      This command block tells APT to “Hold” the MongoDB packages just installed. As the Repository has newer versions of the MongoDB Server available, which will crash with Error -132 if you were to update them, due to the processor onboard a Raspberry Pi 3B+, APT needs to be told to not try to update these packages automatically when APT Update is used.

      Note that this will cause APT to advise that packages are being held back whenever an APT upgrade is performed going forward. You can resolve this by removing the MongoDB Repository from /etc/apt/sources.list.d, but I would advise keeping the Repository around since OS Distribution upgrades can cause MongoDB to be wiped out, which will also nuke your UniFi install and its data in the future. You’ll need the Repository later to re-enable and re-install everything.
  5. Now UniFi Network can be installed.
    1. sudo apt install unifi -y

      This command is self explanatory. It will install the UniFI Network package to the system. Since the Raspberry Pi 3B+ is a bit on the slow side being a decade old at this point, and given the limited I/O performance of the SD Card installed, this will take several minutes to run.

      While this command is running, you can open another Terminal and run the htop command to monitor system resources. You can also visit the Raspberry Pi’s IP Address in a web browser to see if UniFi is starting. For example, if the Raspberry Pi has the IP address 192.168.1.6, visit https://192.168.1.6:8443/ to see if UniFi has started.

      A little pro tip: If UniFi is having issues starting MongoDB, the web server for UniFi will not start. Only after MongoDB has started, and the database begins to build, the web server will start, and you should be greeted with a “UniFi is starting up. Please Wait” screen. This is a great sign that everything up to this point is working correctly. If you see this, wait for several minutes. If the web server does not start, check /var/log/unifi/server.log to see if something is unhappy. Hopefully it is not a MongoDB issue.
    2. Wait for UniFi to bring you to the initial setup screen, which will ask if you are restoring from a backup, or want to create a new site. This can take several minutes to happen. When you see this, proceed to the next step below. We need to make some tweaks for UniFi to run on a Raspberry Pi 3B+.
  6. Since the Raspberry Pi has a limited amount of memory (1GB, ~908MB of which is usable, memory usage for both MongoDB and UniFi need to be trimmed down. Otherwise, the Raspberry Pi will run out of resources within days, and become miserably slow going to swap memory.
    1. systemctl stop unifi

      Stop UniFi first.
    2. sudo nano /usr/lib/unifi/data/system.properties

      This brings up the nano text editor to modify the system.properties configuration file with variables to limit the heap size of Java, and the MongoDB WiredTiger Storage Engine Cache size. Note that this can come with CPU penalties if the UniFi controller will be managing a lot of devices, so such a device is intended more for small sites. UniFi defaults to 1GB of memory, and advises increasing the heap size allowance as an installation grows. From the database side, a lack of database cache can create higher I/O demand on the storage, so these settings may need to be tweaked. These are just what work for me personally at home. For large sites that the Pi is struggling to support, you might just need a faster computer.
    3. Go to the end of the file, and add the following lines:
      unifi.xms=500
      unifi.xmx=500
      db.mongo.wt.cache_size=100

      These lines will tell Java (what UniFi runs on) to take 500MB of RAM to operate, and will restrict the MongoDB Cache to 100MB. These values can be lowered if you need some of that RAM back, for example by setting the xms value to 256 to start, and xmx to a maximum of 450MB, and restricting the MongoDB Cache size to 80MB.
    4. Save the file by pressing Ctrl + X, then press Y when asked if you wish to save changes to the Buffer, then press Enter to overwrite the system.properties file with your changes.
    5. sudo systemctl disable mongod && sudo systemctl stop mongod

      Just in the event that MongoDB, upon installation, became set up as system service, it’s best to disable MongoDB from launching as a service under systemd at boot. UniFi calls MongoDB on its own with launch options specific to UniFi. Additionally, this command will stop the mongod service if it is running. Errors here about the service not running or not being enabled are expected. Proceed ahead even if you get an error.
    6. systemctl start unifi

      With the needed changes completed, the UniFi Controller can be restarted.

At this point, the UniFi Controller should now be configured on the Raspberry Pi, and you should be able to set up the Pi as a new controller, or using a backup.

Hope this helps!

Related Posts