Ubiquiti UniFi wireless access points are extremely popular due to their low cost and their management software capabilities. While many legacy Wi-fi implementations required a dedicated hardware controller, the Ubiquiti UniFi controller can run in software. There are many popular deployment options for the setup. In years past, many on constrained space and budgets would use either AWS instances or virtual machines. That works well but AWS has an additional cost (albeit small) and a VM is a fairly heavy implementation in terms of RAM and disk space. With FreeNAS Corral there is an easy deployment method that we think will be popular for SMB office deployments and high-end home environments: Docker.
Ubiquiti UniFi Controller on FreeNAS Corral in Docker
With FreeNAS Corral there are many new features that you can read about in our overview piece. Two of these features we are going to need for this project: bhyve virtualization, and Docker. Since FreeNAS Corral is based on FreeBSD it utilizes bhyve for virtualization. The UI automatically creates a virtual machine to run a boot2docker Linux image in. While this still requires a VM, for the Ubiquiti UniFi controller, the performance impact is likely immaterial. You can also run multiple Docker containers in the same VM so you are using resources more effectively.
Another great feature is that you can take snapshots of your entire Docker host using ZFS snapshots in FreeNAS. Once the Docker host VM is created, you will have access to a library of containers that are FreeNAS specific. The FreeNAS UniFi container is on Docker hub here.
Towards the end of this list is the pre-build container list is the UniFi controller image. We wanted to offer a few key tips for using this container.
Give the container a descriptive name, and do remember to give it a name as this field is easy to miss. You are unlikely to access this container often.
You will want to set the TZ environment variable. This is used in many systems and you can find a list of options here.
The container uses volumes so you can restart the controller Docker image and still retain your data.
Post Installation
You can login to the Ubiquiti UniFi controller at https://<your FreeNAS system’s hostname or IP address>:8443
After you finish doing the basic admin account setup we have a suggestion: test the power on/ off, restarting the container and etc. Before you invest the time in adopting APs and other devices and setting up the environment, it is best to test the configuration so you are more comfortable should anything go wrong.
When adopting devices, if you use the defaults you are likely to hang at “Adopting”. The most common reason for this when using the FreeNAS Corral Docker UniFi controller is that the UniFi controller will automatically pick up an IP address. It is highly likely that the Docker container will have picked up an IP address of the Docker container, not the LAN IP address of the FreeNAS host and automatically populated the Inform URL. Simply change the IP to the IP/ hostname of the FreeNAS Corral system and the port number will stay the same unless you changed it.
When you have completed your configuration, we highly suggest taking a backup and storing it somewhere safe. If anything ever happens to your UniFi controller you can be up and be running again within 2-3 minutes.
You can find the Backup / Restore features under Settings -> Maintenance.
Closing
This is absolutely trivial to get working. If you run a small business, FreeNAS Corral with its VM capabilities combined with Dockerized applications like this UniFi controller can help eliminate box sprawl and let you consolidate to a minimal footprint. If you do want to use this guide, we highly suggest being on Corral and not an older version like 9.10. The FreeBSD Jails system used in older versions has been replaced (or augmented as it is supposed to be making a comeback) by bhyve and Docker. You could later move the container to another Docker host if your infrastructure expands.
