UniFi Network Application MongoDB Upgrade

UniFi Network Application MongoDB Upgrade
by

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

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.

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.

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

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

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\"} )'"

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 }

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

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

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\"} )'"

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 }

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

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

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 } )'"

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 }

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.

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
UniFi Network Server Settings Backup and Export
Previous post
TrueNAS Expand Zvol
Next post
Exit mobile version