Installing Unifi controller Docker container on Synology NAS

Last Updated on December 30, 2024 by Thiago Crepaldi

A Unifi controller is a required piece of software if you have any Unifi gear, such as their famous Access Points. You can have the controller running on a dedicated hardware, as Unifi Cloud Key or Dream Machine Pro. However, in this post we are going to install the Unifi controller on a Docker container on your Synology NAS!

Before you start

Install Docker on your NAS

First of all, make sure your Synology NAS supports Docker. After login in to your DSM web UI, open Package Center >> All Packages and look for Docker in the list. If it is not installed, do it now! If you can’t find the Docker package, it is probably not supported. Go to Synology website and double check!

Create a configuration folder

We are going to use a folder on your NAS to hold all data from the Docker container. The advantage of this approach is to ease backup and eventual upgrades on the Docker image.

Open File Station and find a share called docker (or any other share, really). In the chosen share, create a unifi-controller subfolder. This folder will have all the important information from your controller, such as configuration, logs, certificates, etc. With this folder, you can delete/upgrade and recreate the container in minutes without losing any configuration!

Install Unifi controller

Installing the Docker image

Once Docker is up and running, we need to download the Docker image that we need to run the controller. There are many flavors out there, but I like jacobalterty/unifi release.

Open Docker and do as follows:

• Click on Registry on the left side menu
• Type ‘unifi’ at the search box on the top of the right panel and press Search
• Select jacobalberty/unifi and click on Download button
• Select ‘latest‘ as tag in the dialog that will be displayed and click on Select
• You can follow the download progress on the Image tab

Configuring Docker container

Once the download is finished, go to Image tab and click on Launch button to create a container instance using jacobalberty/unifi as base image. A simple wizard will take place. Do like this:

• Container name: Any name that you like
• Execute container using high privilege: unchecked
• Enable resource limitation: checked
  • CPU priority: Medium
  • Memory limit: 1024 (maybe 512)
• Click on Advanced Settings button and a new sub-dialog will show up
  • At Advanced Settings tab
    • Enable auto start: checked. Important to run it 24/7!
  • Next go to Volumes tab
    • Click on Add folder and select the one you just created (aka docker/unifi-controller) and press Select
    • Type ‘/unifi’ as Mount path
  • Next go to Networking tab
    • At the bottom of the dialog, check the Use the same network as the Docker Host box
  • Skip Port Settings and Links tabs
  • Lastly, go to Environment tab
    • There will be lots of environment variables for the container
    • Make sure both BIND_PRIV and RUNAS_UID0 are set to false

At the bottom of the wizard window, press Apply followed by Next and review your settings. Finish up by pressing Apply one last time..

Next, the wizard will be closed and your Unifi Controller will start running on port 8443. You can open your browser and visit on https://<your_nas_ip>:8443. Make sure to use https in front of the URL, otherwise the page will not load.

(Optional) Configure your firewall

In case you use Firewall on your Synology or the Unifi controller page doesn’t open, you need to open some ports.

Click on Control panel >> Security >> Firewall and do as follows:

• Click on Edit rules button and a new dialog will appear
  • Click on Create to add a Firewall Rule
    • Under Ports section, select Custom radio box followed by a click on Custom button. A new dialog will show up
      • Type: Destination port
      • Protocol: TCP
      • Ports: 8080,8443,8843,8880,6789
      • Click Ok
    • Source IP: All
    • Action: Allow
    • Click Ok to create the rule
  • Click on Create again to create a second rule
    • Under Ports section, select Custom radio box followed by a click on Custom button. As before, a new dialog will show up
      • Type: Destination port
      • Protocol: UDP 
      • Ports: 3478,10001
      • Click Ok
    • Source IP: All
    • Action: Allow
    • Click Ok to create the rule
• Click Ok to complete the firewall configuration

At this point, Unifi controller page should be accessible. If you still have issues, try rebooting your NAS and try again

(Optional) Updating the Unifi Controller Container

From time to time, a new version of the Image will be pushed to the Docker Hub. It is good practice to update the image to the latest available to ensure security and other critical issues are addressed on your environment. As we used a mapped volume in our setup, upgrade is quick and simple!

Nevertheless, before you start with the update, you should always save a backup of your Unifi Controller. Log in to the controller, go to Settings >> Controller Settings >> Backup. Scroll down to Backup/Restore section and download the backup file.

Updating the Image

The process is identical to the first time you downloaded the jacobalberty/unifi image. In fact, please follow the steps from there and come back here when you are done 🙂

Updating the Container

Now that we have the new image, we need to update the existing container. Click on Container menu and do as follows:

• Stop the unifi controller container by clicking on the switch icon on the right side. When a container is running, the switch shows “0”. After you click on it, it should show “1”
• With the container stopped, select it again and click on Action >> Clear
• A confirmation dialog will appear. Click on Yes to confirm
• Start the container by clicking on the switch again. wait for it to become “0” once again and you are good to go!

(Optional) Install Let’s Encrypt SSL certificates

Using https is great, but sometimes those warnings about invalid or self-signed certificates are annoying. In previous posts I’ve described how to issue Let’s Encrypt SSL certificates on your pfSense and how to install them in your Synology NAS. In this post we will extend this idea and install Let’s Encrypt certificate issued by pfSense into your Unifi controller container, which is running on your Synology. Pretty cool!

The overall idea is to create a periodic task that copies the certificate from pfSense into a local share, tweak it a little bit and then copy them to the container folder, where it will be read by Unifi controller.

Before you start

You can either reuse the same certificate from the aforementioned posts, or create another one with a custom domain name, like unifi.mydomain.com.

For this step-by-step, I will assume that you follow my post on how to issue Let’s Encrypt certificates on your pfSense. I will also assume SSH is enabled on your pfSense.

Open the File Station on your Synology and navigate to docker >> unifi-controller or wherever folder you chose before. Click on Create >> Create folder and type cert as the folder name and press Ok.

Download and save https://github.com/stevejenkins/unifi-linux-utils/blob/master/unifi_ssl_import.sh on your computer. Open it on a file editor and make the following changes:

• Change UNIFI_HOSTNAME to the URL of your NAS
  • UNIFI_HOSTNAME=synology.mydomain.com
• Change LE_MODE
  • LE_MODE=yes

Save the changes and using File Station, upload it into docker/unifi-controller on your Synology NAS.

Automate certificate copy from pfSense

Create a share folder on Synology

If you didn’t already, follow these steps from a previous post to create a Let’s Encrypt share on your NAS

Copying Let’s Encrypt certificate to the Synology Shared folder on a schedule

From the same post, follow these steps to create a scheduled task to copy certificates from pfSense into your NAS. The only difference here is you must copy the certificates into a sub-folder name exactly as the full domain name of your certificate. In other words, if your Synology share is called LetsEncrypt (assuming volume1 for simplicity) and your certificate is issued to synology.mydomain.com, you have to copy the certificates into /volume1/LetsEncrypt/synology.mydomain.com/. This is required by a script that we will use in the next steps.

Installing the certificates on your container on a schedule

Let’s Encrypt certificates expires every 90 days, so pfSense will keep issuing new ones every now and then. That is why we need to create a schedule for this part!

Go to System >> Task Scheduler >> Create >> Scheduled task >> User-defined script and do as follows:

General

• Task: Install certificate on Unifi Controller
• User: root

Schedule

• Run on the following days: Pick the same day as the previous task
• First run time: Pick a time 5 minutes after the one from previous task
• Frequency: Every day

Task settings

User-defined script: use the following template. Change paths accordingly!

# Certificate must be mapped as volume at /unifi/cert inside de docker

# 1. Copy certificates with the right name and permissions
SOURCE_CERT_ALL=/volume1/LetsEncrypt/synology.mydomain.com/synology.mydomain.com.all.pem
SOURCE_CERT=/volume1/LetsEncrypt/synology.mydomain.com/synology.mydomain.comcrt
SOURCE_KEY=/volume1/LetsEncrypt/synology.mydomain.com/synology.mydomain.com.key
SOURCE_CHAIN=/volume1/LetsEncrypt/synology.mydomain.com/synology.mydomain.com.fullchain

# Copying certificate to unifi controller container folder
DEST_CERT_DIR="/volume1/docker/unifi-controller/cert/synology.mydomain.com"
DEST_CERT_ALL="${DEST_CERT_DIR}/cert.all.pem"
DEST_CERT="${DEST_CERT_DIR}/cert.pem"
DEST_KEY="${DEST_CERT_DIR}/privkey.pem"
DEST_CHAIN="${DEST_CERT_DIR}/fullchain.pem"
echo "Copying certificate ${SOURCE_CERT_ALL} to ${DEST_CERT_ALL} for unifi controller container"
echo "Copying certificate ${SOURCE_CERT} to ${DEST_CERT} for unifi controller container"
echo "Copying certificate ${SOURCE_KEY} to ${DEST_KEY} for unifi controller container"
echo "Copying certificate ${SOURCE_CHAIN} to ${DEST_CHAIN} for unifi controller container"
cp -fv ${SOURCE_CERT_ALL} ${DEST_CERT_ALL}
cp -fv ${SOURCE_CERT} ${DEST_CERT}
cp -fv ${SOURCE_KEY} ${DEST_KEY}
cp -fv ${SOURCE_CHAIN} ${DEST_CHAIN}
chmod 600 ${DEST_CERT_DIR}/*
chown 999:999 ${DEST_CERT_DIR}/*

# 2. Import certs into unifi controller
# Modified from https://github.com/stevejenkins/unifi-linux-utils/blob/master/unifi_ssl_import.sh
docker exec unifi-controller bash /unifi/unifi_ssl_import.sh

Click OK to create the scheduled task. Finally click on Run to install certificates that were previously copied from pfSense into a local shared-folder on Synology. That is it! Your Unifi controller will now use Let’s Encrypt certificates and no more annoying warnings should appear!