Upgrade Rocket.Chat from 3.x to 4.0, MongoDB from 4.0 to 5.0 via Docker

0. Background

As of today (20211019), the latest version of Rocket.Chat is 4.0 LTS. MongoDB version 4.0.x is deprecated. So I take this chance to upgrade both to the latest version.

1. Pre-requisite

[IMPORTANT]

(1) MongoDB 5.0 no longer supports storage engine “mmapv1”. The new one is called wiredTiger.
(2) In this case (Rocket.Chat with MongoDB), you cannot upgrade MongoDB directly from 4.0 to 5.0. Instead, you have to upgrade MongoDB from 4.0 to 4.2, then 4.2 to 4.4, and finally 4.4 to 5.0.
(3) For any potential data loss, always make a backup.

2. MongoDB mmap to wiredTiger migration

Assuming your existing docker-compose.yml file is located within /opt/rocketchat.

2.1 Stop your existing Rocket.Chat system including all its services (especially MongoDB)

docker-compose stop

2.2 Clone the repo

git clone https://github.com/RocketChat/docker-mmap-to-wiredtiger-migration /opt/rocketchat-migration

2.3 Copy, move, and rename

cp -r /opt/rocketchat-migration/docker /opt/rocketchat/docker
mv /opt/rocketchat/docker-compose.yml /opt/rocketchat/docker-compose.mmap.yml
cp /opt/rocketchat-migration/docker-compose.yml /opt/rocketchat/docker-compose.yml

2.4 Apply any possible customizations that you had in your old docker-compose.mmap.yml file to the new one (volume, port mappings, service names, etc.)

2.5 Build the "migrator" image and start up the containers again

docker-compose up --build -d

2.6 ​​Wait for the migration to be completed - optionally check logs of "migrator" and "mongo" containers

docker-compose logs -f migrator # once that one has completed the migration
docker-compose logs -f mongo # ... check if the mongo one already took over

3. Upgrade Rocket.Chat from 3.x to latest (4.0)

3.1 Put back your original docker-compose.yml, instead of the migration one

docker-compose down
mv /opt/rocketchat/docker-compose.yml /opt/rocketchat/docker-compose.yml.bak
mv /opt/rocketchat/docker-compose.mmap.yml /opt/rocketchat/docker-compose.yml

3.2 Upgrade Rocket.Chat

This is quite straightforward. Just down the container and remove older version of image. Change image version to “latest”. Then re-up the container.

4. Upgrade MongoDB from 4.0 to 5.0

Similar to Rocket.Chat upgrade, but as mentioned earlier, you have to upgrade small version by small version. And you have to enable features that persist data incompatible with earlier versions of MongoDB.
Change the Mongo version from 4.0 to 4.2 in docker-compose.yml, for both MongoDB and its replicaSet

docker-compose up -d
docker-compose exec mongo bash -c 'mongo --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"4.0\" } )"'
docker-compose down

Change the Mongo version from 4.2 to 4.4 in docker-compose.yml, for both MongoDB and its replicaSet

docker-compose up -d
docker-compose exec mongo bash -c 'mongo --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"4.2\" } )"'
docker-compose down

Change the Mongo version from 4.4 to 5.0 in docker-compose.yml, for both MongoDB and its replicaSet

docker-compose up -d
docker-compose exec mongo bash -c 'mongo --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"4.4\" } )"'