Deploying a Ubiquiti Unifi appliance with Ansible

Unifi Application screenshots as per Unifi’s own product page

I finally got tired of my old 802.11n Apple Airport Express(!) that has been serving the kitchen part of our house with an Internet connection for many years. Effectively it tops out at ~100Mbps speeds and has pretty poor range. It is being replaced by a Ubiquiti Unifi6 Lite access point.

In preparation for this, I decided to set up a local instance of the Unifi network application on a VM. While researching the install process, I found an excellent and apparently blessed by Ubiquiti shell script that installs the prerequisites and the application. After reading it through I see nothing wrong with the current version, but as it is almost 160 KB of text and there’s no kind of verification that what you download actually is what the author intended, I’m not entirely comfortable running it blindly. Instead I took a couple of hours to understand what it does and ported its main features to Ansible, resulting in a completely readable 2 KB playbook.

What’s missing compared to the original script is a) certificate management via Let’s Encrypt, and b) cleanup of failed previous installations, removal of invalid prerequisite software versions, etc.
For a) in my network I would set up the certificate request/renewal on my reverse proxy which already has all the required bits in place, and then copy the valid certificate to the Unifi server and restart the services using recurring cron jobs.
For b) I prefer the cattle way of managing servers: Running the playbook against a fresh Ubuntu installation ensures I don’t have to deal with – possibly even manually configured and undocumented – cruft.

The Ansible role can be downloaded from my Git repo here.

As the people at Ubiquiti provide a dpkg/.deb repository, this work had the added benefit of forcing me to generalize my KVM virtual machine deployment playbook a bit:
I had started out with an extremely simple Cloud-Init config which worked well with the Fedora Server cloud-base image, but which made no sense on the Ubuntu Server equivalent. The new version works well with both of them, and can be downloaded from this Git repo.


  1. Funny coincidence, just this week I’ve stumbled upon that megascript for Unifi and thought to myself: “No way I’m ever reading that wall of text”. I don’t have any Unifi devices so my inquiry into this was pure curiosity. If I was ever to run Unifi controller I’d probably choose Docker container over that shell blackbox. Your Ansible role is actually readable by humans, thanks for that.

    I also enjoyed reading your VM deployment role – it’s actually very similar to mine. Your role looks like it’s not idempotent, do you use it in one-off playbooks only?

    Do you have any other public repos on your GitLab instance?

  2. Hi, thanks for commenting!
    Yes, the Unifi controller is a good fit for dockerization too of course.

    The VM deployment role is only used in my home environment at a one-off basis, as you guessed. In a production environment I would put in a bit more work to account for edge cases and (resumption from) failures, of course.

    As for your final question: no, these are the first two projects I’ve decided to share publicly. Additional ones will surely follow. EDIT: I had forgot that I also shared an example config for integration of Bind9 and ISC-DHCP in an earlier post.

Comments are closed.