How do I run Ubiquiti's UniFi Network Controller on macOS?

Solution 1:

I'm aware of two different ways to do this.

Using Docker

The LinuxServer.io team maintains a Docker image for the UniFi Network Controller. I haven't tried to use it and don't know how hard it is to get up and running or how well it works, so unfortunately I can't compare it to the other option. However, after having gone through the steps to install natively I'll say that the idea of using a Docker container is quite appealing.

Installing Natively

This works fine and isn't tremendously difficult to get running, but it is unfortunately more work than it should be.

1. Download your preferred version

   Look for "UniFi Network Controller [version] for macOS" on the Unifi download page. If you have no preference then go with the newest version.

2. Install Network Controller

   Find UniFi.pkg in Finder. Control+click and select Open with... → Installer. Without this macOS complains that "'UniFi.pkg' can’t be opened because Apple cannot check it for malicious software." Then select "Open" if prompted and proceed through the installer.

3. Install Java 8

   The release notes state:

   We stopped bundling Java as of UniFi Network 5.11.47. If you're installing that release or later please make sure you have manually installed a current release of Java 8 beforehand. Only the Java Runtime Environment (JRE) is required.

   and

   An updated/current version of Java 8 must be installed on the system hosting the controller software. Java 9 and later are not yet supported.

   So you'll need to use an old version of Java. This is inconvenient and also a little worrying considering Java 8 is quite old and Java doesn't have a great track record when it comes to security vulnerabilities. According to Wikipedia, Oracle officially ended free commercial updates in January 2019 and will end free personal-use updates in December 2020. Wikipedia says the AdoptOpenJDK package will be supported until "at least September 2023." That sounded good to me so that's what I used. Installing with Homebrew is easy:

   1. Follow the instructions to install Homebrew if you don't already have it.
   2. In a terminal, run brew tap homebrew/cask-versions and brew install --cask temurin8

4. Adjust your firewall

   Navigate to System Preferences → Security & Privacy → the Firewall tab. Click the lock in the bottom left corner to allow changes then click the Firewall Options... button. Uncheck Block all incoming connections. No other changes are required—click OK to save.

   A few notes:

   • If Automatically allow downloaded signed software to receive incoming connections is checked then that seems to be sufficient to give Network Controller access (I assume because the Homebrew java package is signed).
   • If Automatically allow downloaded signed software to receive incoming connections is unchecked then you'll be prompted to allow incoming connections when Network Controller is started.
   • Adding Applications/UniFi to the list of apps with allowed incoming connections doesn't work.
   • Instead of doing all the above stuff you could alternatively completely turn off your firewall, but I don't recommend it. Firewalls provide a useful layer of protection.
   • These steps might be different if you're using macOS earlier than 10.5.1. You might need to unblock specific ports, instead. See this help article for the list of ports.

5. Start the Network Controller

   I've found that starting Network Controller appears to hang unless I cd to a specific directory. And remember that you'll need to use Java 8.

   cd /Applications/UniFi.app/Contents/Resources/
   JAVA_VERSION=1.8 java -jar /Applications/UniFi.app/Contents/Resources/lib/ace.jar ui
   

   If macOS asks, Do you want the application 'java' to accept incoming network connections? you must click Allow for Network Controller to work correctly.

Two follow-up notes:

1. You can undo any changes to your firewall when you're done with the Network Controller (assuming you're not planning on leaving it running all the time). Though the firewall changes are mostly harmless if all you did was allow java to receive incoming connections.

2. You can also run the Network Controller "headlessly." I haven't tried it, but the instructions at https://akrabat.com/run-the-unifi-controller-headless-on-mac/ look promising. Note that you'll need to use a different exec string than the ones suggested on that page.