UniFi Network Application MongoDB Upgrade

If you have been using the UniFi controller for a very long time, there’s a chance you are running an older version of MongoDB. When Ubiquiti released version 8.1 of the UniFi network application server, they finally bumped up the supported MongoDB version from 4.4 to 7.0.

The MongoDB upgrade path only supports jumping one major version at a time, and some manual steps are needed. Yes, you could take a settings-only backup and reroll the whole setup, but where’s the fun in that?

In this post, I will show you step-by-step how to upgrade the Mongo database version from 4.4 to 7.0 for the Unifi network application server running on docker.

Prerequisites

• Backup your UniFi config. My blog post, UniFi Network Server Settings Backup and Export, covers how to do this.
• Running UniFi network application version 8.1 or newer.
• The service name of the MongoDB for UniFi from your docker compose file.
• The container name of your MongoDB for UniFi.

The Process

The entire process revolves around docker exec as we will execute commands directly into the Mongo database container.

You can follow this process on other UniFi controller setups that aren’t done with docker. However, I’ve only validated the process with on a docker setup, but the command structure would be similar.

To be extra safe during this process, I will bring down my UniFi docker stack and only bring up my UniFi database container.

I will run the command docker compose down to bring the UniFi controller offline. This helps ensure the UniFi network application doesn’t try to write to the database while the database is upgrading.

• Bring up the MonogoDB container for UniFi with the following command. Replace Mongo_Service_Name with the service name for MongoDB from your docker compose file. sudo docker compose up Mongo_Service_Name -d

If you are using my docker compose setup from my blog post, UniFi Network Server with Docker, the MongoDB service name will be unifi-net-app-db

For me, the command will be sudo docker compose up unifi-net-app-db -d

Before starting any upgrades, let’s double-check which version of MongoDB is installed and what the compatibility level is currently set to. We will do that by using the MongoDB shell with the command mongo. We will tell Mongo that we will provide some commands from which we want the output by using the argument eval followed by our commands.

The command to check which version of MongoDB we are running and what our compatibility level is set to is the following command db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

To run this against our Mongo docker container, we will use docker exec with a shell command followed by the mongo shell commands we want to run.

• Run the following command to check what MongoDB version is running. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

For me, the command looks like

sudo docker exec unifi-net_DB sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

Your output should be something like this

MongoDB server version: 4.4.29
{ "featureCompatibilityVersion" : { "version" : "4.4" }, "ok" : 1 }

The output above confirms that we are running MongoDB 4.4, and our feature compatibility is set to the same version.

If you get an error that mongo is not found, this is due to running a newer version of MongoDB that no longer supports the mongo command as that command has been deprecated in newer versions.

The replacement command for mongo is mongosh. However, the output differs from the old mongo command when gathering the compatibility levels.

We need to tweak our command a bit to get a similar output. We need to include a call for the database version. We can do that with the command db.version(). If we want the MongoDB version and the feature compatibility level all in one command, we need to use the print command and combine them.

The new mongosh command will look like this mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"

The full docker command will look something like this sudo docker exec Mongo_Container_Name sh -c 'mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"'

With that command, we will get the MongoDB version on the first line and the feature compatibility level on the second line. That is everything we need.

The upgrade path for MongoDB is long, as MongoDB does not support jumping higher than one major version at a time. Meaning if you are running MongoDB 4.4, you need to upgrade a few times before you can get to MongoDB 7.0

The upgrade path is MongoDB 4.4 to 5.0, MongoDB 5.0 to 6.0, and MongoDB 6.0 to 7.0. The upgrade path must be followed.

Now that we know which MongoDB version we are running, we can follow the upgrade path. In my example, I am running MongoDB 4.4.

MongoDB 4.4 to 5.0

• Bring down your UniFi docker stack with the command docker compose down.

• Edit your docker-compose.yml file and change the Mongo image version from 4.4 to 5.0.

• Run docker compose pull to download the new MongoDB image.

• Bring up the MonogoDB container for UniFi with the following command. Replace Mongo_Service_Name with the service name for MongoDB from your docker compose file. sudo docker compose up Mongo_Service_Name -d

If you are using my docker compose setup, the MongoDB service name will be unifi-net-app-db

For me, the command will be sudo docker compose up unifi-net-app-db -d

• Run the following command to confirm that you are running MongoDB 5.0 and your feature compatibility level is 4.4. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

For me, the command looks like

sudo docker exec unifi-net_DB sh -c 'mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"'

You should get an output similar to this.

5.0.27
{ featureCompatibilityVersion: { version: '4.4' }, ok: 1 }

Now that we know we are running Mongo 5.0 with a compatibility level of 4.4, we can upgrade the compatibility level from 4.4 to 5.0.

To upgrade the compatibility level, we need to run the command db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )

We will take that command and inject it into our docker exec command. We also need to add \ before the " because we need to escape the quotes as they will conflict with our other command quotations.

The command should look something like this docker exec unifi-net_DB sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"5.0\"} )'"

• Run the following command to upgrade your feature compatibility level to 5.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"5.0\"} )'"

For me, that command will look like

sudo docker exec unifi-net_DB sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"5.0\"} )'"

You should then get an output of { ok: 1 }

• Run the following command to confirm that your feature compatibility level has been upgraded to 5.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

For me, the command looks like

sudo docker exec unifi-net_DB sh -c 'mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"'

You should get an output similar to this.

5.0.27
{ featureCompatibilityVersion: { version: '5.0' }, ok: 1 }

Now, we can move on to the next upgrade.

MongoDB 5.0 to 6.0

• Bring down your UniFi docker stack with the command docker compose down.

• Edit your docker-compose.yml file and change the Mongo image version from 5.0 to 6.0.

• Run docker compose pull to download the new MongoDB image.

• Bring up the MonogoDB container for UniFi with the following command. Replace Mongo_Service_Name with the service name for MongoDB from your docker compose file. sudo docker compose up Mongo_Service_Name -d

If you are using my docker compose setup, the MongoDB service name will be unifi-net-app-db

For me, the command will be sudo docker compose up unifi-net-app-db -d

• Run the following command to confirm that you are running MongoDB 6.0 and your feature compatibility level is 5.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

For me, the command looks like

sudo docker exec unifi-net_DB sh -c 'mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"'

You should get an output similar to this.

6.0.15
{ featureCompatibilityVersion: { version: '5.0' }, ok: 1 }

Now that we know we are running Mongo 6.0 with a compatibility level of 5.0, we can upgrade the compatibility level from 5.0 to 6.0.

To upgrade the compatibility level, we need to run the command db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )

We will take that command and inject it into our docker exec command. We also need to add \ before the " because we need to escape the quotes as they will conflict with our other command quotations.

The command should look something like this docker exec unifi-net_DB sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"6.0\"} )'"

• Run the following command to upgrade your feature compatibility level to 6.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"6.0\"} )'"

For me, that command will look like

sudo docker exec unifi-net_DB sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"6.0\"} )'"

You should then get an output of { ok: 1 }

• Run the following command to confirm that your feature compatibility level has been upgraded to 6.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

For me, the command looks like

sudo docker exec unifi-net_DB sh -c 'mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"'

You should get an output similar to this.

6.0.15
{ featureCompatibilityVersion: { version: '6.0' }, ok: 1 }

Now, we can move on to the next upgrade.

MongoDB 6.0 to 7.0

• Bring down your UniFi docker stack with the command docker compose down.

• Edit your docker-compose.yml file and change the Mongo image version from 6.0 to 7.0.

• Run docker compose pull to download the new MongoDB image.

• Bring up the MonogoDB container for UniFi with the following command. Replace Mongo_Service_Name with the service name for MongoDB from your docker compose file. sudo docker compose up Mongo_Service_Name -d

If you are using my docker compose setup, the MongoDB service name will be unifi-net-app-db

For me, the command will be sudo docker compose up unifi-net-app-db -d

• Run the following command to confirm that you are running MongoDB 7.0 and that your feature compatibility level is 6.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

For me, the command looks like

sudo docker exec unifi-net_DB sh -c 'mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"'

You should get an output similar to this.

7.0.11
{ featureCompatibilityVersion: { version: '6.0' }, ok: 1 }

With Mongo version 7, we now need to confirm the compatibility upgrade operation, so we need to add confirm: true to the compatibility level upgrade command.

To upgrade the compatibility level, we need to run the following command db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } )

We will take that command and inject it into our docker exec command. We also need to add \ before the " because we need to escape the quotes as they will conflict with our other command quotations.

The command should look something like this docker exec unifi-net_DB sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"7.0\", confirm: true } )'"

• Run the following command to upgrade your feature compatibility level to 7.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"7.0\", confirm: true } )'"

For me, that command will look like

sudo docker exec unifi-net_DB sh -c "mongosh --eval 'db.adminCommand( { setFeatureCompatibilityVersion: \"7.0\", confirm: true } )'"

You should then get an output of { ok: 1 }

• Run the following command to confirm that your feature compatibility level is upgraded to 7.0. Replace Mongo_Container_Name with the name of the MongoDB container that you are using with UniFi. sudo docker exec Mongo_Container_Name sh -c 'mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"'

For me, the command looks like

sudo docker exec unifi-net_DB sh -c 'mongosh --eval "print(db.version());print(db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ))"'

You should get an output similar to this.

7.0.11
{ featureCompatibilityVersion: { version: '7.0' }, ok: 1 }

Final Step

Now that you have upgraded to the highest version currently supported by the UniFi controller, we can bring everything back online.

• Bring down your UniFi docker database with the command docker compose down.

• Bring up your UniFi docker stack with the command docker compose up -d.

You are now running your UniFi Network Application server on the highest version of MongoDB currently supported by UniFi.

If you want to read more about the Mongo database upgrade process, here is the Mongo documentation.

Related posts:

UniFi Network Server with Docker UniFi Network Server Settings Backup and Export Aruba Access Point Firmware Upgrade Onyx (MLNX-OS) Upgrade