website-hadow.fr/_posts/2025-12-18-how-to-upgrade-a-mongodb-container.md

layout, author, tags

layout	author	tags
post	Sam Hadow	podman mongodb sysadmin

On my server I self host Overleaf with containers (podman) and Overleaf requires MongoDB as a database. Each version of Overleaf has a minimum required version of MongoDB and therefore you might have to upgrade your MongoDB container at one point. I'll explain step by step how I did it in my case.

Upgrade steps

As stated in the official documentation, MongoDB requires step by step upgrades.
The intermediary version when upgrading (starting from version 4.0) are:
4.0, 4.2, 4.4, 5.0, 6.0, 7.0, 8.0

In my case I had to upgrade from version 6.0 to version 8.0

I now have the following in my Mongodb systemd unit managing the container:

[Unit]
Description=Podman container-overleaf-mongo.service
Documentation=man:podman-generate-systemd(1)
Wants=network-online.target
After=network-online.target
RequiresMountsFor=%t/containers
BindsTo=pod-overleaf.service
After=pod-overleaf.service

[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
Restart=on-failure
TimeoutStopSec=70
ExecStart=/usr/bin/podman run \
	--cidfile=%t/%n.ctr-id \
	--cgroups=no-conmon \
	--rm \
	--pod-id-file %t/pod-overleaf.pod-id \
	--sdnotify=conmon \
	--replace \
	-d \
	-e MONGO_INITDB_DATABASE=sharelatex \
	-v /home/data/podman/overleaf/mongo_data:/data/db:Z \
	-v /home/data/podman/overleaf/initdb.js:/docker-entrypoint-initdb.d/mongodb-init-replica-set.js:z \
	--name overleaf-mongo \
	"--health-cmd=echo \"db.stats().ok\" | mongosh localhost:27017/test --quiet" \
	--health-interval=10s \
	--health-timeout=10s \
	--health-retries=5 \
	docker.io/library/mongo:8.0 \
	--replSet overleaf
ExecStop=/usr/bin/podman stop \
	--ignore -t 10 \
	--cidfile=%t/%n.ctr-id
ExecStopPost=/usr/bin/podman rm \
	-f \
	--ignore -t 10 \
	--cidfile=%t/%n.ctr-id
Type=notify
NotifyAccess=all

[Install]
WantedBy=default.target

The important line is:

	docker.io/library/mongo:8.0 \

Where MongoDB version is stated, originally it was 6.0.
When upgrading you need to follow these steps:

• bring the container down
• change the systemd unit with the next release and reload systemd daemons
• bring the container up
• set feature compatibility in MongoDB to the version you upgraded to
• repeat until you upgraded to the desired version

With commands it gives the following:

systemctl --user stop container-overleaf-mongo.service  # then change the unit file
systemctl --user daemon-reload
systemctl --user start container-overleaf-mongo.service
podman exec -it overleaf-mongo mongosh --eval 'db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })'        # to see which version the feature compatibility is currently set to
podman exec -it overleaf-mongo mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })'   # to set the feature compatibility to another version (here 7.0)

Then I had to repeat the same steps to upgrade from 7.0 to 8.0.

Command outputs

Here are example outputs when running with podman exec commands in a MongoDB container:

1. Getting MongoDB version (not the feature compatibility, only the version of MongoDB)

Command:

podman exec overleaf-mongo mongod --version

Output:

db version v7.0.26
Build Info: {
    "version": "7.0.26",
    "gitVersion": "715b3bbc6c34cecc42ffc77ef77d24f71e240e94",
    "openSSLVersion": "OpenSSL 3.0.2 15 Mar 2022",
    "modules": [],
    "allocator": "tcmalloc",
    "environment": {
        "distmod": "ubuntu2204",
        "distarch": "x86_64",
        "target_arch": "x86_64"
    }
}

In this case the major version is 7.0.

2. Getting feature compatibility version

Command:

podman exec -it overleaf-mongo mongosh --eval 'db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })'

Output:

{
  featureCompatibilityVersion: { version: '6.0' },
  ok: 1,
  '$clusterTime': {
    clusterTime: Timestamp({ t: 1763739555, i: 108 }),
    signature: {
      hash: Binary.createFromBase64('AAAAAAAAAAAAAAAAAAAAAAAAAAA=', 0),
      keyId: Long('0')
    }
  },
  operationTime: Timestamp({ t: 1763739555, i: 108 })
}

Here we can see that the feature compatibility version is 6.0 (even though MongoDB was at version 7.0).

3. Upgrading feature compatibility version

If we simply run:

podman exec -it overleaf-mongo mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "7.0" })'

Then MongoDB gives us this warning (downgrades are not possible):

MongoServerError: Once you have upgraded to 7.0, you will not be able to downgrade FCV and binary version without support assistance. Please re-run this command with 'confirm: true' to acknowledge this and continue with the FCV upgrade.

If we indeed want to upgrade we need to run this command:

podman exec -it overleaf-mongo mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })'

And we should get an ouput like this:

{
  ok: 1,
  '$clusterTime': {
    clusterTime: Timestamp({ t: 1763739614, i: 2 }),
    signature: {
      hash: Binary.createFromBase64('AAAAAAAAAAAAAAAAAAAAAAAAAAA=', 0),
      keyId: Long('0')
    }
  },
  operationTime: Timestamp({ t: 1763739614, i: 2 })
}