Upgrading RocketChat Deployed in Docker

This is a guide to upgrading RocketChat deployed in Docker.

RocketChat can be easily upgraded by updating the “RocketChat” container version in your docker-compose.yml file. Once you have updated the version:

docker pull rocketchat/rocket.chat:latest
docker-compose stop rocketchat
docker-compose rm rocketchat
docker-compose up -d rocketchat

This will upgrade RocketChat to any 4.x version. Beginning in RocketChat 5.0, There is a requirement to be running at least MongoDB v4.2. If you are running RocketChat v4.x with MongoDB v4.0, you are seeing a message from the RocketChat bot indicating that Mongo v4.0.28 is deprecated and should be upgraded.


The upgrade of MongoDB is a multi-step process. Mongo v4.0.28 uses the mmap database engine. Before MongoDB can be upgraded to the next version which is MongoDB v4.2, you must change the MongoDB database engine in Mongo v4.0.x from the mmap engine to the wiredTiger database engine.

I have tried this procedure several times and failed before I discovered the solution. To begin with, your docker-compose.yml file MUST be located in the /opt/rocketchat folder before this can work.

Initially, my RocketChat was installed in a /docker/rocketchat folder and so this did not work.

To prepare for the upgrade:

docker-compose down
mkdir /opt/rocketchat
mv docker-compose.yml /opt/rocketchat/docker-compose.yml
mv data /opt/rocketchat/data
mv uploads /opt/rocketchat/uploads

Check your docker-compose.yml and make sure that you have an existing volume for the dump folder defined:

Also make sure that the ./data/dump folder exists.

Now create a database dump of your existing MongoDB:

docker-compose up -d
cd /opt/rocketchat
docker-compose exec mongo mongodump --archive=/dump/mmap --gzip
cp ./data/dump/mmap ~/mongo-mmap-dump.gzip

Stop your existing RocketChat:

docker-compose stop

Download the repository for the database engine remapping tool:

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

Copy the docker folder that has the dockerfile for the migrator image into your existing compose folder:

 cp -r /opt/rocketchat-migration/docker /opt/rocketchat/docker

Backup and rename your existing docker-compose.yml file:

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

Copy the new docker-compose.yml file into your compose folder. You should leave this docker-compose file in place after the upgrade because it is built to support future migrations as well:

 cp /opt/rocketchat-migration/docker-compose.yml /opt/rocketchat/docker-compose.yml

Review the new docker-compose in case you had any customizations that you need to include.

Now build the migrator image:

docker-compose up --build -d

This may take five minutes or more to complete in the background.

Once this completes, your RocketChat should be up. Go to the admin – info section and look at the database section. It should say "MongoDB 4.0.x / wiredTiger (oplog Enabled)

Congratulations, you are now using the required wiredTiger database engine with Mongo 4.0.x which is a prerequisite before moving to MongoDB 4.2.

Now we need to upgrade MongoDB. The latest version of MongoDB is 5.0.x to support RocketChat.

Unfortunately, we cannot upgrade from 4.0 to 5.0 directly. The upgrade path is:

Mongo 4.0 ----> Mongo 4.2
Mongo 4.2 ----> Mongo 4.4
Mongo 4.4 ----> Mongo 5.0

***To go from Mongo 4.0 to Mongo 4.2:
Edit your docker-compose.yml and replace the 4.0 with 4.2 in the mongo section and in the mongo-init-replica section.


Once this is completed, perform the following:

docker-compose stop mongo
docker-compose rm mongo
docker-compose up -d mongo

We now have to change the replication feature set in the database. Connect to the Mongo container. You may need to explicitly specify the name by first doing a “docker ps” to see what it is called:

docker exec -it mongo bash

Now that you are connected to the container:

db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )

You should now be running mongoDB 4.2. Repeat the procedure above beginning at step “***” and this time change the 4.2 to 4.4. Finally, repeat the procedure again to go from 4.4 to 5.0.

Once everything is completed, go into your RocketChat and go to admin – info and it should appear as follows:
upgraded rocketchat