UniFi - How to Install & Upgrade the UniFi Controller Software


Overview


This article will explain how to upgrade the UniFi Controller software on various supported platforms. The process for installation and upgrading is close to the same, aside from a few considerations this article will expose. Please follow the steps below for both installation and upgrading. 

NOTES & REQUIREMENTS:
This article covers installation and upgrade on macOS, Windows and Windows Server and Debian-based Linux (Ubuntu, Mint, and others). For instructions specific to the UniFi Cloud Key Controller, please see this article.

Table of Contents


  1. Finding the Current Controller Version
  2. Minimum and Recommended System Requirements
  3. UniFi Installation and Upgrade on Debian-Based Linux
  4. UniFi Installation and Upgrade on Windows
  5. UniFi Installation and Upgrade macOS
  6. Related Articles

Finding the Current Controller Version


Back to Top

To find the most current stable version of the UniFi Controller software please visit the software section of the downloads site here

Warning: Do not attempt to install an older software version over a newer software version. There are database protections in line to prevent the controller from starting if this has been performed. 

Minimum and Recommended System Requirements


Back to Top

These are the minimum system requirements for the UniFi Controller to run optimally. It is important to read the Release Notes of each UniFi Controller software version release. It will include any special considerations to keep in mind before installing. A link to the Release Notes will he available in the Downloads page along with the corresponding software version, or find all past Release Notes in the UniFi Updates Blog

Operating System:

  • Linux
    • Ubuntu Desktop / Server 14.04 or 16.04 (recommended)
    • Debian 7 “Wheezy”, 8 "Jessie", 9 "Stretch" (recommended)
  • Windows
    • Windows 7 or Windows 10 (recommended)
    • Windows Server 2008 or 2016 (recommended)
  • macOS
    • Mavericks 10.9, 10.10 Yosemite, 10.11 El Capitan, 10.12 Sierra, 10.13 High Sierra, 10.14 Mojave (10.14 recommended)

CPU: x86-64 Processor (Intel / AMD x64 Processors)*

RAM: 2GB*

Network: 100Mbps Wired Ethernet*

HDD: Minimum 10GB free (20GB or more preferred)*

Java: Java Runtime Environment (JRE) 8

Web Browser: Google Chrome

MongoDB: version 3.2 or later (Mongo is offered bundled: default bundled is 2.4.14 (for macOS and Windows only)).

*NOTE: Actual Storage, CPU, RAM, and Network speed requirements will depend on many factors including the number of UniFi devices managed by the controller, number of clients, features enabled, and data retention settings. For database repair, you require free space equal to the current database size, plus 2GB.

UniFi Installation and Upgrade on Debian-Based Linux 


Back to Top

ATTENTION: Before attempting an upgrade it is a good idea to have a current backup in the event that the upgrade fails or a downgrade is needed.
CLI: Access the command line interface (CLI). You can do this by using an SSH client to a Linux host or by opening the console from the Linux GUI. 

1. Open our Downloads page.

2. Navigate to the Software section and find the newest Debian/Ubuntu Linux entry.

3. Select Download and click "I Accept" if you accept the terms.

4. Copy the URL.

5. SSH or open a console to the Controller host. 

6. Switch to the /tmp/ directory.

cd /tmp/

7. Download the .deb file with wget. This is where the copied URL comes into play. Hit enter after the URL copied on step 4 is pasted.

wget PASTE_THE_URL_HERE
NOTE: At this point, the .deb file will download to the /tmp/ directory. How quickly this completes is based on the host's throughput to the internet. 

8. After the download completes, use dpkg to unpack the .deb file and install the new Controller version.

sudo dpkg -i unifi_sysvinit_all.deb
NOTE: The filename referenced above should be used. If it is not, the file name can be referenced from the wget command output. Remember to be in the /tmp/ directory when running the dpkg command or it will look for the file in the /home/ directory. During this time the UniFi Controller is unable to process any requests. Client data will still pass through the devices.

9. When Upgrading: The installer will run through the process of upgrading the UniFi Controller software. A prompt will come up asking if you have a sufficient backup on hand. Select yes if you do or no if you do not.

When Installing: A message about dependency problems may appear. Type in the following command and hit enter:

sudo apt-get install -f

10. After the process completes the command prompt will return to entry. The controller software should be upgraded or installed successfully at this point.

11. To access the Controller open a browser window and navigate to: 

 https://<IP_of_Controller_host>:8443

If the Controller service is running the software should prompt with a webpage.

User Tip: Other commands that might be useful are:
To start UniFi if the webpage prompt does not appear: sudo service unifi start
To stop the UniFi service: sudo service unifi stop
To restart the UniFi service: sudo service unifi restart
To see the status of UniFi service: sudo service unifi status

UniFi Installation and Upgrade on Windows 


Back to Top

ATTENTION: Before attempting an upgrade it is a good idea to have a current backup in the event that the upgrade fails or a downgrade is needed.

1. Open our Downloads page.

2. Navigate to the Software section and find the newest Windows entry.

Ubiquiti_Networks_-_Downloads.png

3. Select Download and click "I Accept" if you accept the terms.

4. Select Download File

NOTE: At this point, the .exe file will download to the selected folder location. How quickly this completes is based on the host's throughput to the internet. 

5. Close UniFi by exiting the status window found when clicking on the system tray icon.

NOTE: During this time the UniFi Controller is unable to process any requests. Client data will still pass through the devices.

6. Open the .exe file and navigate through the install wizard. 

7. After completion of the install wizard, you may open the UniFi program.

8. To access the controller open a browser window and navigate to: 

 https://<IP_of_Controller_host>:8443

If the Controller service is running the software should prompt with a webpage.

9. The Controller should be operational.

Considerations When Running UniFi as a Windows Service

Reference the upgrading section from UniFi - Run the Controller as a Windows Service.


UniFi Installation and Upgrade on macOS


Back to Top

ATTENTION: Before attempting an upgrade it is a good idea to have a current backup in the event that the upgrade fails or a downgrade is needed.

1. Open our Downloads page.

2. Navigate to the Software section and find the newest macOS entry.

Ubiquiti_Networks_-_Downloads.png

3. Select Download and click "I Accept" if you accept the terms.

4. Select Download File

NOTE: At this point, the .pkg file will download to the selected folder location. How quickly this completes is based on the host's throughput to the internet. 

5. Close the UniFi Controller software.

6. Open UniFi.pkg and complete the steps in the installer.

7. If the installation process was run with success you will see a message that says The installation was successful

8. To access the controller open a browser window and navigate to: 

 https://<IP_of_Controller_host>:8443

If the Controller service is running the software should prompt with a webpage.


Related Articles


Back to Top

Intro to Networking - How to Establish a Connection Using SSH

UniFi - Run the Controller as a Windows Service

UniFi - How to Install & Update via APT on Debian or Ubuntu

UniFi - Controller Fails to Start When Opened

UniFi - How to Manage & Upgrade your Cloud Key

UniFi - How to Change the Cloud Key's Controller Version via SSH


We're sorry to hear that!