Developing software in the Real World

Run the UniFi Controller headless on Mac

I’m running a UniFi network here with wireless access points, the Security Gateway and a PoE switch. It seems to be a robust system and is almost certainly overkill, but reliability is high on my lists after bad experiences with a NetGear WiFi router.

The UniFi system software is called the Controller and runs on a various operating systems. As I have a Mac mini here, I decided to run it on there. Weirdly, however it runs as a GUI application which means that I have to be logged in. There’s no need for that though as by scouring the Internet I discovered that we can run it headless via launchd.

Firstly we create /Library/LaunchDaemons/com.unifi.controller.service.plist. This file has to be owned by root with group of wheel:

This is a fairly standard launchd plist file file. However, the controller software is written in Java, but as Ubiquiti no longer bundle a copy of Java, we need to install our own copy of Java 8:

(You may need change the path to where your Java 8 is installed.)

This means that when Ubiquiti updates the bundled Java, our service continues to work. We also need to set the working directory to the Resources directory of the app bundle as it doesn’t work otherwise…

Update: Since this post was written, Ubiquiti no longer bundle Java, I have updated appropriately based on the comment from Wade Gibson.

Secondly, we install the service:

Now, the Controller is always running and we can access it on https://localhost:8443 and manage our UniFi network to our heart’s content!

17 thoughts on “Run the UniFi Controller headless on Mac

  1. Hi Rob….

    What an amazing article….. I have read pages and pages worth of complex solutions and articles on Unifi forum but your methos got me up and running less than 2min.

    Thanks million for this post

  2. Forgive a silly question:
    First install and get the controller working, as gui, no?
    Does it matter the controller version?

    Thank You!

  3. Hello all,
    it indeed worked.
    Just to add, maybe it will help somebody –
    to create plist owned by root and with group wheel you have to manually create plist file with that name (lets say on desktop), copy it to LaunchDaemons and use terminal:

    and then start service

    Thanks rob for quick help.

  4. Hi all, I have rolled the above including Raul’s comments. Only difference is using folder LaunchAgents.

    Does not load on reboot, but wors when I sign in, I don’t have to launch app.

    I would like it to run on reboot, without logging in. please help

  5. It took a little digging around, but changing this line in the plist with the new Java path seems to work. You have to put quotes around it since the path has a space.

    1. You are a life saver! Every time the controller is updated, I've literally been copying and pasting the bundled version of Java from an older versions of the Controller into the new UniFi.app package. I knew there had to be a way to point to the manually installed version of Java.

      Still really frustrating the Ubiquiti unbundled Java (though it appears to be due to Oracle's terrible licensing), and even worse that the Controller is still written in Java…

  6. Rob- I've been looking, for weeks now, for a fix to my UniFi.app not launching on my mac. I tried everything on the Ubiquity community pages and zilch. This did the trick – along with additional feedback from Raul and Wade. Thank you all!

  7. To run UniFi controller as a faceless app with version 5.12.66 simply did the change in Info.plist file
    change "ui" to "start"
    From:
    JVMOptions

    To:
    JVMOptions

    Then run:

    After that you can do whatever you want, e.g. use launchd
    Mine:

    Label
    com.ubiquiti.unifi
    Disabled

    RunAtLoad

    ProgramArguments

    /Applications/UniFi.app/Contents/MacOS/JavaAppLauncher

    UserName
    put_user_name_here
    ServiceDescription
    Unifi Manager

    1. That last bit, enabling it from launchd – a few questions:
      Do you remove the LaunchDaemon plist file that we created based on this post?
      You have the settings, but I'm using old school editor (vi) so it would help see all the xml tags, can you put your contents of com.ubiquiti.unifi.plist in this thread?

      Thank You

  8. Pingback: Making Game: How do I run Ubiquiti's UniFi Network Controller on macOS? - TECHPRPR
  9. Pingback: Linux HowTo: How do I run Ubiquiti's UniFi Network Controller on macOS? - TECHPRPR

Leave a Reply to Rob Cancel reply

Your email address will not be published. Required fields are marked *