Updating Mongo version

From version 2.0.0 until 2.4.2 we haven't been too specific about which version of Mongo should be used with Overleaf Community Edition and Overleaf Server Pro, with the exception for the minimum supported version specified in supported dependencies list.

Starting on 2.5.0, any new release will indicate any change on the supported version of Mongo in its release notes.

Similarly, the version of mongo docker image in docker-compose.yml has been historically untagged. Starting on Overleaf CE/SP 2.5.0, the tag will be updated to the version supported by the latest release of Overleaf CE/SP.

Should I update Mongo?

You should only consider updating Mongo version if you're planning to upgrade your instance of Overleaf CE/SP.

If you're running a Mongo version that is newer than the recommended for your current (or target) version (e.g, Overleaf CE/SP 2.4.0 along with Mongo 4.2) there's no need to make any changes. You should never downgrade your Mongo version.

If you experience a specific problem that you think might be related to your current version of Mongo, feel free to raise an issue (CE users) or contact support (SP users).

Checking your Mongo version

Opening the mongo shell should immediately print the current version.

➤ docker-compose exec mongo mongo -version
MongoDB shell version v4.4.1

Toolkit users:

➤ bin/docker-compose exec mongo mongo -version
MongoDB shell version v4.4.1

Update Process

Updating the version of Mongo during an upgrade of your Overleaf CE/SP instance is as follows:

1. Decide the version of Overleaf CE/SP you plan to upgrade to.
2. Find the version of Mongo recommended by that specific Overleaf CE/SP release.
3. Follow the instructions to upgrade Mongo to the target version.
4. Upgrade Overleaf CE/SP image version and restart the instance.

Our recommendation is to always upgrade Overleaf CE/SP to the latest version available, since it's always guaranteed to be supported (Server Pro Users only). In case you decide to go to an earlier version, this table shows the recommended version of Mongo for earlier releases of Overleaf CE/SP, but you should never downgrade your Mongo version.

CE/SP Version	Mongo Version
2.0.x	3.4
2.1.x to 2.4.x	3.6
>=2.5.0	4.0
>=3.1.0	4.2
>=3.2.0	4.4
>4.2.0 (*)	5.0

* Mongo 4.4 will hit End-of-life in February 2024, users running 4.2.x can safely update to Mongo 5.0 in preparation for the next CE/Server Pro release.

Upgrading Mongo

Mongo requires step-by-step upgrades. That means you can't go straight from, let's say 3.2 to 3.6. You need first to update 3.2 to 3.4, and then 3.4 to 3.6 (Mongo uses even numbers for their stable versions).

Update instructions when running mongo outside docker

• From 3.2 to 3.4
• From 3.4 to 3.6
• From 3.6 to 4.0
• From 4.0 to 4.2
• From 4.2 to 4.4
• From 4.4 to 5.0

Note that the instructions for 5.0 point to a replica set install, instead of standalone. Mongo needs to be run as a replica set since Server Pro 4.0.1.

Docker users

• Update the version of the mongo image (docker-compose setup: edit services -> mongo -> image; Toolkit setup: update MONGO_IMAGE, e.g. MONGO_IMAGE=mongo:5.0)

In most cases the update just requires setting up a compatibility setting before actually updating the version. Let's see an example.

Example: upgrading Mongo from 3.4 to 3.6

Let's start by making sure we're running Mongo 3.4:

➤ docker-compose exec mongo mongo -version
MongoDB shell version v3.4.24

Toolkit users:

➤ bin/docker-compose exec mongo mongo -version
MongoDB shell version v3.4.24

According to the upgrade instructions, the only requirement is to have featureCompatibilityVersion set to 3.4. We do so by opening a mongo shell and running the indicated command:

➤ docker-compose exec mongo mongo
MongoDB shell version v3.4.24
connecting to: mongodb://127.0.0.1:27017
MongoDB server version: 3.4.24
Welcome to the MongoDB shell.
For interactive help, type "help".
> db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )
{ "ok" : 1 }
> exit
bye

Toolkit users:

➤ bin/docker-compose exec mongo mongo
MongoDB shell version v3.4.24
...
> db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )
{ "ok" : 1 }
> exit
bye

We'll then stop the Overleaf CE/SP and Mongo instances (docker-compose down; Toolkit: bin/stop), update docker-compose.yml to use image: mongo:3.6 (Toolkit: set MONGO_IMAGE=3.6 in config/overleaf.rc), and then restart mongo (docker-compose up mongo; Toolkit: bin/up mongo) to verify the update went smoothly.

Finally, we'll update Overleaf CE/SP image version to our target version and restart all the services (docker-compose up; Toolkit: bin/up -d).