I recently purchased two UniFi nanoHD access points but not a Cloud Key. How can I run the Network Controller on my macOS computer?

1 Answer

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

Using Docker

This might be a good option if you're already familiar with Docker, but it may not be worth the learning curve otherwise. It appears there are two well-maintained Docker images for the UniFi Network Controller.

• The LinuxServer.io team's Docker image. I haven't tried it but it looks like a decent choice.
• An image from a guy named Jacob Alberty. I have tried this one and it works well.

Extra effort must be made to make adoption work when running in Docker. The default network type for Docker (bridge) means containers are not accessible on the network. For Layer 2 adoption, the documentation for Jacob Alberty's image mentions using host networking or the macvlan network. I've used host networking with this Docker image in Linux and it works well, however at the time of this writing (2022-04-10) host networking is not available in macOS Docker Desktop. I haven't tried using macvlan but it might work well (with either image, even though the LinuxServer.io documentation doesn't mention it). For Layer 3 adoption, it looks like you must enter the Docker host's IP in the UniFi Network Controller's settings (the documentation for both Docker images has details of where to find the setting).

The Jacob Alberty image appears to include some support for specifying an https certificate. I haven't tried it, but if using a certificate trusted by your browser is important for you then this might be a reason to choose the Jacob Alberty image.

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/
   JAVA_VERSION=1.8 java -jar /Applications/ 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 look promising. Note that you'll need to use a different exec string than the ones suggested on that page.

8