How to Update your UniFi controller docker

Updating your UniFi Controller running in a Docker container is an essential task to keep your network running smoothly and securely.

Whether you're rolling out the latest features, patching a critical vulnerability, or just staying up-to-date with the latest and greatest, this guide will walk you through the entire process step-by-step. We’ll make it fun, easy, and maybe even a bit entertaining.

Let's Dive In!

Table of Contents

• Why should you update your UniFi controller?
• Step 1: Check your current version
• Step 2: Prepare your Docker environment
• Step 3: Backup your current settings
• Step 4: Pull the latest Docker image
• Step 5: Stop and remove the existing container
• Step 6: Start the new container
• Step 7: Verify the update
• Step 8: Restore your backup (if necessary)
• Step 9: Troubleshooting tips
• Rolling back to a previous version
• Final Thoughts

Why should you update your UniFi controller?

Let’s start with the basics. Why bother updating your UniFi Controller in the first place? Well, for starters, Ubiquiti (the folks behind UniFi) regularly releases updates that include new features, bug fixes, performance improvements, and—most importantly—security patches.

Keeping your controller updated ensures that your network is running at its best and is protected against the latest security threats.

Plus, who doesn’t love playing with new features? Each update might bring something cool to your UniFi setup that you didn’t even know you needed. Whether it’s improved device management, better reporting, or new integrations, staying up-to-date keeps you ahead of the curve.

Step 1: Check your current version

Before diving into the update, it’s a good idea to know where you’re starting from. Log into your UniFi Controller through your web browser. Once you’re in, you’ll see the current version of your controller displayed at the bottom of the page or within the settings menu.

Take note of this version number. It’s always good to have a reference point, just in case something goes sideways and you need to verify that the update worked as expected.

Step 2: Prepare your Docker environment

Now that you know where you stand, it’s time to prepare your Docker environment for the update. If you’re running your UniFi Controller in Docker, you’re probably familiar with the basics of Docker and Docker Compose. If not, don’t worry—we’ll walk you through it.

First, open up a terminal on your server or wherever your Docker environment is running. Navigate to the directory where your Docker Compose file is located. This file should define how your UniFi Controller container is set up. If you’re not sure where this is, it might be in a folder like "/home/user/unifi" or something similar.

Here’s how you might navigate to it:

cd /path/to/your/docker-compose

Once you’re in the right directory, take a moment to review your "docker-compose.yml" file. This file contains the configuration for your UniFi Controller, including which Docker image it’s using. If it’s been a while since you’ve updated this file, now is a good time to make sure everything is up to date.

Step 3: Backup your current settings

Backing up your UniFi Controller settings is crucial before you start the update process. You’ve likely spent a lot of time configuring your network just the way you like it, and the last thing you want is to lose all that hard work.

There are a couple of ways to back up your settings. The easiest is to use the built-in backup feature in the UniFi Controller. Here’s how:

1. Go to Settings > Maintenance > Backup within your UniFi Controller interface.

2. Click Download Backup and save the file to a secure location.

This backup file will contain all your settings, device configurations, and more. If anything goes wrong during the update, you can use this file to restore your controller to its previous state.

Alternatively, if you prefer to back up the entire Docker container’s data, you can copy the volume data using a simple Docker command:

docker cp unifi:/unifi/data /your/backup/location

This command will copy all the data from your UniFi container to a directory on your server. It’s a good idea to do both types of backups just to be safe.

Step 4: Pull the latest Docker image

Now that your backups are secure, it’s time to pull the latest UniFi Controller Docker image. This is the image that contains the newest version of the UniFi Controller software. To pull the latest image, simply run the following command in your terminal:

docker pull jacobalberty/unifi:latest

This command fetches the most recent version of the UniFi Controller image from Docker Hub. The "jacobalberty/unifi" image is one of the most popular and frequently updated images for running the UniFi Controller on Docker, and it’s well-maintained by the community.

Step 5: Stop and remove the existing container

Before you can start running the new image, you’ll need to stop and remove the existing UniFi Controller container. Don’t worry—your data is safe as long as you’ve set up persistent volumes correctly.

To stop the running container, use this command:

docker stop unifi

Next, remove the container with:

docker rm unifi

These commands stop and delete the old container, freeing up resources and making room for the new one. Remember, this doesn’t delete your data; your settings and configurations are stored separately in the Docker volumes.

Step 6: Start the new container

With the old container out of the way, it’s time to fire up the new one. If you’re using Docker Compose, this is as simple as running:

docker-compose up -d

The "-d" flag runs the container in detached mode, meaning it will run in the background, freeing up your terminal for other tasks.

If you’re not using Docker Compose, you can start the container manually with a command like this:

docker run -d --name unifi \
  
  -p 8443:8443 \
  
  -p 3478:3478/udp \
  
  -p 10001:10001/udp \
  
  -p 8080:8080 \
  
  -p 1900:1900 \
  
  -e TZ='Europe/London' \
  
  -v /path/to/unifi:/unifi \
  
  jacobalberty/unifi:latest

Make sure to replace "/path/to/unifi" with the actual path to your persistent data volume.

Step 7: Verify the update

Once the new container is up and running, it’s time to check that everything is working as expected. Open your web browser and log into the UniFi Controller just as you normally would. Check the version number displayed on the login screen or within the settings menu. It should match the latest version you pulled in step 4.

Take a few moments to click around and ensure that all your settings, devices, and configurations are intact. If everything looks good, then congratulations—you’ve successfully updated your UniFi Controller!

Step 8: Restore your backup (if necessary)

If something didn’t go according to plan and your settings or configurations were lost, don’t panic. You can easily restore your controller to its previous state using the backup file you created earlier.

To restore from a backup:

1. Go to Settings > Maintenance > Restore in the UniFi Controller interface.

2. Upload the backup file you saved earlier.
3. Wait for the controller to restore your settings.

After restoring, everything should be back to the way it was before you started the update process.

Step 9: Troubleshooting tips

No guide would be complete without a few tips for dealing with potential issues. Here are some common problems you might encounter during the update and how to solve them:

• Container won’t start: If your new container won’t start, check the Docker logs for errors. You can view the logs by running "docker logs UniFi".

• Missing data: If your data is missing after the update, make sure your Docker volumes are correctly mapped. Your persistent data should be stored in a volume that wasn’t deleted when you removed the old container.

• Network issues: If you’re having trouble connecting to the UniFi Controller after the update, double-check your Docker network settings and ensure all required ports are properly mapped.

Rolling back to a previous version

If for some reason the new version isn’t working out for you, rolling back to a previous version is simple. Just pull the Docker image for the version you were using before, and follow the same steps to stop, remove, and restart the container:

docker pull jacobalberty/unifi:VERSION_TAG

Replace "VERSION_TAG" with the specific version number you want to roll back to. This will allow you to revert to the older, stable version while you troubleshoot any issues with the latest update.

Final Thoughts

Updating your UniFi Controller in Docker is an essential part of keeping your network secure and running smoothly. With a few simple commands and a bit of preparation, you can ensure that your controller is always up to date with the latest features and security patches.

Here at UniHosted, we understand that managing updates and backups can be time-consuming. That’s why we offer managed UniFi Controller hosting services.