How To Install And Set Up UniFi Controller On Ubuntu: Enterprise Deployment Guide

Host your own Ubiquiti network management platform by setting up the UniFi Network Application on Ubuntu Server LTS. This deployment requires configuring a compatible Java Runtime Environment, provisioning a dedicated MongoDB database instance, and adjusting firewall permissions to allow uninterrupted device telemetry. Following this certified process ensures your controller achieves maximum system stability, secure device adoption, and optimal performance for hundreds of connected access points and switches.

Pre-Installation Architecture and Resource Allocation

Deploying a self-hosted UniFi Network Application (formerly known as the UniFi Controller) on Ubuntu provides system administrators with absolute control over their network configuration, telemetry storage, and update cycles. Before running any commands, you must establish an appropriate deployment environment. This includes selecting a compatible Ubuntu Long Term Support (LTS) release—Ubuntu 22.04 LTS or Ubuntu 24.04 LTS are highly recommended—and planning your hardware allocation based on the scale of your managed infrastructure.

A common pitfall in self-hosted deployments is under-provisioning storage and memory. The UniFi Controller writes frequent operational logs and system metrics to its database. If database writes are delayed due to resource starvation, devices will repeatedly show a Heartbeat Missing status or isolate themselves. Ensure your target host fits into one of the following resource profiles and meets the core system requirements:

• Essential Gear and Platforms: A physical bare-metal server, a local Kernel-based Virtual Machine (KVM/Proxmox), or a Virtual Private Server (VPS) hosted on platforms like DigitalOcean, Linode, or AWS.
• Small Network Resources (1 to 10 UniFi Devices): 2 Virtual CPUs, 2 Gigabytes of system RAM, and 20 Gigabytes of solid-state storage (SSD).
• Medium Network Resources (11 to 100 UniFi Devices): 2 to 4 Virtual CPUs, 4 Gigabytes of system RAM, and 50 Gigabytes of solid-state storage (SSD).
• Large Network Resources (100+ UniFi Devices): 4 or more Virtual CPUs, 8 to 16 Gigabytes of system RAM, and 100+ Gigabytes of high-performance solid-state storage (SSD) configured with enterprise-grade write endurance.
• Mandatory Network Standards: A statically assigned IPv4 address on your local area network (LAN) or a fully qualified domain name (FQDN) mapped via public DNS to ensure managed UniFi access points can always reach the host.
• Project Duration: Approximately 20 minutes of administrative execution time.
• Estimated Budget: Zero software licensing fees, as the Ubuntu operating system, Java OpenJDK, MongoDB, and the UniFi Network Application are free to use.

Complete Step-by-Step Installation and System Provisioning

Step 1: Operating System Optimization and Static IP Assignment

To prevent your managed network devices from losing connection to the controller, the hosting Ubuntu server must possess a permanent, static IP address. Begin by establishing an SSH connection to your Ubuntu machine as a privileged user.

First, update your local package lists to ensure you retrieve the absolute latest security patches. Run the command:

sudo apt-get update

Next, execute the upgrade command to apply all pending system patches:

sudo apt-get upgrade -y

Once the update completes, install essential administrative tools, including curl, gnupg2, and ca-certificates, by executing:

sudo apt-get install -y curl nano gnupg2 ca-certificates lsb-release

To assign a static IP address, open your Netplan configuration file. This file is typically located in the /etc/netplan/ directory and ends in a .yaml extension. Open it using the nano text editor:

sudo nano /etc/netplan/00-installer-config.yaml

Modify the network interface configuration to disable DHCP and assign your static IP parameters. Ensure your configuration mirrors this structure, adjusting the interface name, addresses, gateway, and DNS servers to match your local network architecture:

network: version: 2 renderer: networkd ethernets: eth0: dhcp4: no addresses: - 192.168.1.50/24 routes: - to: default via: 192.168.1.1 nameservers: addresses: [1.1.1.1, 8.8.8.8]

Save the file by pressing Ctrl+O, exit using Ctrl+X, and apply the configuration by executing:

sudo netplan apply

Verify the change was successful by outputting your active IP configuration:

ip addr show eth0

Step 2: Provisioning MongoDB for UniFi Storage

The UniFi Network Application relies on MongoDB to manage its operational database. Version 8.x and higher of the UniFi Controller are compatible with MongoDB versions up to 7.0, while older 7.x releases rely on MongoDB 4.4.

Warning: Modern versions of Ubuntu (such as Ubuntu 22.04 LTS and 24.04 LTS) do not natively ship with the legacy libssl1.1 library, which is a hard dependency for older MongoDB releases like MongoDB 4.4. If you are deploying an older UniFi version that requires MongoDB 4.4, you must manually install this helper library.

To install libssl1.1 on modern Ubuntu, download the package directly from the security archives:

curl -LO http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb

Install the downloaded package using the Debian package manager:

sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb

Now, import the official MongoDB public GPG signing key to verify the integrity of the database packages:

curl -fsSL https://www.mongodb.org/static/pgp/server-4.4.asc | gpg --dearmor | sudo tee /usr/share/keyrings/mongodb-org-4.4.gpg > /dev/null

Create the official MongoDB repository list file:

echo "deb [signed-by=/usr/share/keyrings/mongodb-org-4.4.gpg] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

Refresh your package manager sources to pull database metadata from the newly added repository:

sudo apt-get update

Install the MongoDB database server package along with its necessary utility tools:

sudo apt-get install -y mongodb-org

Once installed, reload the systemd configuration manager to recognize the new unit files, configure the service to launch automatically when the server boots, and start the daemon:

sudo systemctl daemon-reload

sudo systemctl enable mongod

sudo systemctl start mongod

Verify that MongoDB is running successfully in the background by checking its status:

sudo systemctl status mongod

Step 3: Installing the Correct Java Runtime Environment (JRE)

The UniFi Controller is a Java-based web application. It requires a specific JRE version to run properly. Modern releases of the UniFi Network Application (specifically version 8.0 and higher) run on OpenJDK 17, whereas legacy versions require OpenJDK 11.

Install the headless edition of OpenJDK 17, which does not include graphical user interface overhead, by executing:

sudo apt-get install -y openjdk-17-jre-headless

If you are running an older, legacy version of the UniFi controller, substitute the package name with openjdk-11-jre-headless instead. Once installed, confirm the active runtime version by executing:

java -version

Ensure the terminal output confirms the presence of OpenJDK version 17.0.x or 11.0.x respectively.

Step 4: Adding the Official Ubiquiti Repositories and Installing UniFi

With Java and MongoDB configured, you are ready to import the official Ubiquiti Debian/Ubuntu repository. Import the Ubiquiti public GPG key to verify the authenticity of the UniFi application installation packages:

curl -fsSL https://dl.ui.com/unifi/unifi-repo.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/unifi-repo.gpg > /dev/null

Add the official Ubiquiti software repository to your system sources list:

echo "deb [signed-by=/usr/share/keyrings/unifi-repo.gpg] https://www.ui.com/downloads/unifi/debian stable unifi" | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

Update your system's package indices to incorporate the newly imported repository metadata:

sudo apt-get update

With all dependencies met, install the UniFi Network Application package:

sudo apt-get install -y unifi

After the system completes the installation process, the UniFi daemon starts automatically. Register the controller as a system service to guarantee it boots with the server:

sudo systemctl enable unifi

sudo systemctl start unifi

Check the active status of the service to ensure the application has successfully initiated:

sudo systemctl status unifi

Step 5: Configuring the Host-Level Firewall (UFW)

A secure UniFi deployment requires that only required ports are exposed to incoming traffic, preventing unauthorized external communication while allowing network devices to report in safely. The standard tool for this is the Uncomplicated Firewall (UFW).

Pro-Tip: Always verify your active SSH port is explicitly allowed through the firewall before enabling UFW. Failure to do so will result in an immediate termination of your SSH terminal session, locking you out of the remote server.

To secure your server, execute the following commands in sequence to permit SSH, Web GUI administration, STUN, and device communication:

sudo ufw allow 22/tcp

sudo ufw allow 8080/tcp

sudo ufw allow 8443/tcp

sudo ufw allow 3478/udp

sudo ufw allow 10001/udp

sudo ufw allow 1900/udp

Enable the firewall and apply these configurations:

sudo ufw enable

Verify the active ruleset to ensure the ports match the requirements:

sudo ufw status verbose

Step 6: Initializing the Web Setup Wizard

Now that the background services are fully running, you must complete the controller's initial initialization wizard using a graphical web browser.

Open a web browser on a workstation located on the same network as your server. In the address bar, navigate to the static IP address of your Ubuntu host on port 8443 using the secure HTTPS protocol. For example:

https://192.168.1.50:8443

Your browser will present a security warning because the controller issues a self-signed SSL certificate by default. Accept the warning and choose to proceed to the website.

Follow the prompts of the UniFi Setup Wizard:

1. Name your new UniFi Controller.
2. Sign in with your Ubiquiti Single Sign-On (SSO) account credentials, or select Advanced Setup to create a local-only administrator account for enhanced privacy.
3. Configure your automated backup schedules.
4. If your network switches or access points are on the same local subnet as the controller, they will appear in the device discovery screen. Select the devices you wish to manage and click Adopt.
5. Set up your primary Wi-Fi Network Name (SSID) and Security Key if managing a UniFi Access Point.
6. Review your settings and click Finish to launch the management dashboard.

Controller Network Ports and Service Matrix

The following table serves as a reference for configuring network routing, external firewalls, or Docker environments associated with your self-hosted UniFi Controller.

Troubleshooting Common Controller Failures

Issue 1: MongoDB Service Fails to Start Due to AVX CPU Limitation

• Root Cause: MongoDB version 5.0 and newer requires the Advanced Vector Extensions (AVX) CPU instruction set. If your Ubuntu instance is running on an older physical server, or is hosted as a virtual machine on a hypervisor configured with a generic virtual CPU model, the MongoDB process will crash immediately upon startup, outputting an Illegal Instruction core dump.
• Actionable Fix: If your underlying hardware does not support AVX, you must downgrade MongoDB to version 4.4, which does not enforce the AVX instruction set requirement. Alternatively, if running under a virtual environment like Proxmox or ESXi, access your hypervisor settings and change the VM's CPU Type from Default/Generic to Host, which exposes the physical CPU's instruction set directly to the Ubuntu operating system.

Issue 2: UniFi Web GUI Fails to Load with Port 8080 or 8443 Conflict

• Root Cause: Another service running on your Ubuntu host is already listening on ports 8080 or 8443 (such as Apache, Tomcat, or Docker containers). This binds the port and prevents the UniFi Controller from initializing.
• Actionable Fix: Identify the offending process by running the command: sudo netstat -lntp | grep -E "8080|8443". If netstat is not installed, install it or run: sudo ss -lntp | grep -E "8080|8443". Stop or reconfigure the conflicting service. If you must change the UniFi Controller's default listening ports, open its configuration properties file: sudo nano /var/lib/unifi/system.properties. Find the lines starting with unifi.http.port and unifi.https.port, remove the prepended hash symbol, modify the port values to unused numbers, save the changes, and restart the controller: sudo systemctl restart unifi.

Issue 3: UniFi Service Stuck in a Loop of Constant Restarts

• Root Cause: This is frequently caused by insufficient system memory or invalid permissions on database directories. When Java attempts to initialize the application heap space and runs out of allocatable RAM, it triggers an abrupt system halt.
• Actionable Fix: Open the UniFi environment configuration file: sudo nano /etc/default/unifi. Locate the line starting with UNIFI_JVM_MAX_HEAP_SIZE. Adjust this parameter to set a hard limit that leaves at least 512 Megabytes of free system RAM for MongoDB and operating system overhead. For a 2GB RAM server, add: UNIFI_JVM_MAX_HEAP_SIZE=1024M. Next, reset the directory ownership permissions to ensure the unifi system user owns all runtime logs and database directories: sudo chown -R unifi:unifi /var/lib/unifi /var/log/unifi /var/run/unifi. Restart the controller service to apply the fixes: sudo systemctl restart unifi.

Frequently Asked Questions

Can I run the UniFi Controller on Ubuntu 24.04 LTS safely?

Yes. Although Ubuntu 24.04 LTS is a newer OS release, you can run the UniFi Controller without issues by manually configuring the official OpenJDK 17 runtime and ensuring you deploy a compatible database engine like MongoDB 7.0, which resolves old library compatibility mismatches.

How do I update my self-hosted UniFi Controller when new software versions are released?

Since you installed the application utilizing the official Ubiquiti APT repository, updating your controller is integrated directly into the standard Ubuntu update flow. To update, simply connect to your server via SSH and execute the commands: sudo apt-get update && sudo apt-get install --only-upgrade unifi -y. The package manager will safely swap the application files while preserving your database, site configurations, and adopted devices.

What is the default path to restore backups if the web interface is unavailable?

If you are performing a recovery operation or migrating from an older controller, manual backup archives are stored on the server at /var/lib/unifi/backup/. You can transfer backup files into this directory using SFTP or SCP, rebuild your server, and select these backup configurations during the initial setup wizard.

How do I modify the default Java memory allocation manually?

Modify the JVM memory settings by editing the /etc/default/unifi configuration file using nano. Locate the heap size setting and assign it a value suited for your server (e.g., -Xmx1024M for 1GB maximum heap size, or -Xmx4096M for 4GB maximum heap size) to ensure the controller operates efficiently under heavy client loads.

Elevating Your Network Infrastructure

Maximize your infrastructure's efficiency and secure your connected endpoints by utilizing our enterprise deployment consulting services. Contact our technical engineering team today to design, secure, and monitor your distributed self-hosted controller architecture.