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

Question

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

Answer 1

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 Application.

• 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 Application'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 Application [version] for macOS" on the Unifi download page. If you have no preference then go with the newest version.

2. Install Network Application

   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 11

   Note from 2023-08-27: You can try skipping this step—it might not be needed anymore. I was able to install version 7.4.162 and I think I don't have Java installed, so it might be bundled now. Or I could be wrong. I don't see anything about it in the release notes.

   Note: Versions prior to 7.3.x required Java 8 so if you've chosen to install an older version of the Network Application then see an earlier revision of this answer for advice on installing Java 8 and also the command for starting older versions of the Network Application.

   For versions 7.3.x and newer you need Java 11. (As of 2023-01-13 the release notes state "Java 12 and later are not yet supported." Presumably Java 13 through 19 are also not supported.)

   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 install openjdk@11. For me this installed 24 dependencies, too.
   3. As suggested by the output of the above command, create a symlink to allow the system Java wrappers to find this JDK: sudo ln -sfn /usr/local/opt/openjdk@11/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-11.jdk

4. Adjust security settings

   Note: These instructions changed significantly due to the Settings overhaul in macOS 13 Ventura. You can reference an earlier revision of this answer for guidance on macOS 12 and older, but also note that those instructions might be inaccurate for newer versions of the Network Application and Java 11.

   1. Navigate to System Settings → Network. Select Firewall then click the Options... button. Ensure Block all incoming connections is off. No other changes are required. Click OK to save.

      A few notes:

      • If Automatically allow downloaded signed software to receive incoming connections is enabled then that is sufficient to give Network Application access.
      • If Automatically allow downloaded signed software to receive incoming connections is disabled then you'll be prompted to allow incoming connections when Network Application is started.
      • Proactively adding Applications/UniFi to the list of apps with allowed incoming connections doesn't seem to work. I don't know why. But it's not important—macOS will prompt you about it later, if needed.
      • Instead of the above firewall changes you could completely turn off your firewall, but I don't recommend it. Firewalls provide a useful layer of protection.

   2. Attempt to start the Network Application. You'll use this process anytime you need to start it in the future: Either run the UniFi app from the Applications folder or use ⌘+Space and search for "UniFi." You should get this error dialog:

      

   3. "Damaged" is not accurate—macOS is just preventing it from running correctly. Click the Cancel button then navigate to System Settings → Privacy & Security. Scroll down past all the applications and look for the "Security" heading. You should see the following dialog:

      

   4. Use the "Open Anyway" button to approve it. You'll get a second dialog that says the application is damaged:

   

   5. I have no idea what macOS is complaining about here. Ignore this and click the "Open" button. (Side note: This area of the macOS user experience really needs work.)

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

Two follow-up notes:

1. You can undo any changes to your firewall when you're done with the Network Application (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 UniFi to receive incoming connections.

2. You can also run the Network Application "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.

Answer 2

I got it working in docker in a few simple steps! I've made a docker config on guthub with full instructions, but here are the basic steps:

1. Decide where UniFi should save persistant data on your machine.

2. Run a docker compose script.

3. Browse to https://localhost:8443 and complete the initial setup.

4. Go to settings and enter the IP address of your machine.