Rocket.Chat – The Full Update Summary

Rocket.Chat & MongoDB Upgrade Documentation

Version Jump:  v5.0.3 $\to$→ v6.x $\to$→ v7.13.4. Date: March 2026

---

Rocket.Chat & MongoDB Compatibility Matrix

• Rocket.Chat 7.x: MongoDB 6.0, 7.0 (5.0 deprecated).
• Rocket.Chat 6.x: MongoDB 5.0, 6.0 (4.4 deprecated).
• Rocket.Chat 5.x: MongoDB 4.4, 5.0 (4.2 deprecated).

+---------------------------------------------------------------+
|                         SERVER RUNNING                        |
+---------------------------------------------------------------+
|                                                               |
|  Rocket.Chat Version: 5.0.3                                   |
|       NodeJS Version: 14.21.3 - x64                           |
|      MongoDB Version: 5                                       |
|       MongoDB Engine: WildTiger                               |
|             Platform: linux                                   |
|         Process Port: 3000                                    |
|             Site URL: https://chat.remote-tech.us             |
|     ReplicaSet OpLog: Enabled                                 |
|          Commit Hash: 54bc7edd11                              |
|        Commit Branch: HEAD                                    |
|                                                               |
+---------------------------------------------------------------+

** NEVER JUMP MAJOR RELEASES **

UPGRADE PATH

1. Upgrade Rocket.Chat from 5.03 to 6
   • Update UNRAID template changing image tag to 6
     • Restart and verify
       • Logs indicated deprecated settings:
         • Removed:
           • -e 'USE_NATIVE_OPLOG'='true' (deprecated in v6+).
         • Added:
           • -e 'IGNORE_CHANGE_STREAM'='true' 
           • -e 'EXIT_UNHANDLEDPROMISEREJECTION'='true‘
     • Verify Completed Rocket.Chat 6 with MongoDB 5
2. Upgrade MongoDB from 5 to 6
   • Update UNRAID template changing image tag to 6
     • Restart and verify
       • Logs indicated presented error:
         • “Unrecognized option: storage.journal.enabled” 
           • This occurred because MongoDB removed this configuration option in version 6.1 and later. In these versions, journaling is always enabled by default and cannot be toggled via this parameter. 
         • Fix:
           • Manually edited mongod.conf to remove the deprecated journaling toggle required for MongoDB 6.1+.
           • # journal:
           • # enabled: true
     • Verify Completed Rocket.Chat 5 with MongoDB 6
   • Pin MongoDB:
     • docker exec -it MongoDB bash
     • mongosh -username $DB_USER -password $DB_PASS
     • db.adminCommand({setFeatureCompatibilityVersion: "6.0", confirm: true})
3. Upgrade Rocket.Chat from 6 to 7
   • Update UNRAID template changing image tag to 7
     • Restart and verify
     • Verify Completed Rocket.Chat 7 with MongoDB 6
4. Upgrade MongoDB from 6 to 7
   • Update UNRAID template changing image tag from 6 to 7
     • Restart and verify
     • Verify Completed Rocket.Chat 7 with MongoDB 7
   • Pin MongoDB
     • docker exec -it MongoDB bash
     • mongosh -username $DB_USER -password $DB_PASS
     • db.adminCommand({setFeatureCompatibilityVersion: "7.0", confirm: true})
       • Upon attempting to finalize the database upgrade to 7.0, MongoDB issued a critical warning:
       • “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…”
       • User Feedback/Decision: 
       • To address the concern of a permanent, irreversible change,
       • we decided to perform a full mockup restore to justify moving forward.

BACKUP & RESTORE PROCEDURE

1. Start a New Test Container

<em># Remove the old failed test container</em>
docker rm -f MongoTest

<em># Start a fresh one using the official image and updated variables</em>
docker run -d --name MongoTest \
  -p 27018:27017 \
  -e MONGODB_INITDB_ROOT_USERNAME=admin \
  -e MONGODB_INITDB_ROOT_PASSWORD=password \
  mongo:7.0

2. Restore the Backup

Wait about 10 seconds for the database to initialize, then run the restore:

cat /mnt/user/bak_db/mongo_backups/mongo_backup_20260316_202810.archive.gz | \
docker exec -i MongoTest mongorestore \
  --username=admin --password=password --authenticationDatabase=admin \
  --gzip --archive

3. Verify Your Rocket.Chat Data

Confirm that your specific Rocket.Chat collections (like users and rocketchat_message) exist in the new container:

docker exec -i MongoTest mongosh -u admin -p password --eval "db.getSiblingDB('rocketchat').getCollectionNames()"

If you see the list of Rocket.Chat collections, your backup is 100% verified. 
You can then safely return to your main MongoDB shell and run the FCV upgrade:

<code>db.adminCommand({setFeatureCompatibilityVersion: "7.0", confirm: true})

That version: '7.0' confirms your database is officially current.

Important Support Note

Your current version (7.13.4) is officially supported until June 30, 2026.  

Why You Should Wait

• Database Incompatibility:
  • Your current setup uses MongoDB 7.0, but Rocket.Chat 8.2 requires MongoDB 8.0 or higher to run. Upgrading the application now would cause it to fail on startup due to this database version mismatch.
• Stability Risks:
  • Version 8.2.1 is a very recent release. Early adopters have already reported critical issues, such as empty chats and authentication problems after upgrading to the 8.2.x branch.
• “Point of No Return”:
  • Just like your recent FCV 7.0 change, major version jumps (from 7.x to 8.x) often involve architectural changes that make downgrading extremely difficult if the new version is unstable for you.

Recommended Next Steps

1. Stay on 7.13.4:
   • This version is fully supported until June 30, 2026.
   • You have several months of safety before you need to move to the 8.x branch.
2. Plan Your MongoDB Upgrade:
   • Before you can move to Rocket.Chat 8.2, you will eventually need to upgrade your MongoDB instance to version 8.0.

+---------------------------------------------------------------+
|                         SERVER RUNNING                        |
+---------------------------------------------------------------+
|                                                               |
|  Rocket.Chat Version: 7.13.4                                  |
|       NodeJS Version: 22.22.1 - x64                           |
|      MongoDB Version: 7.0.25                                  |
|       MongoDB Engine: WildTiger                               |
|             Platform: linux                                   |
|         Process Port: 3000                                    |
|             Site URL: https://chat.remote-tech.us             |
|     ReplicaSet OpLog: Enabled                                 |
|          Commit Hash: 54bc7edd11                              |
|        Commit Branch: HEAD                                    |
|                                                               |
+---------------------------------------------------------------+

4. Rocket.Chat Application Upgrade

Everything is now synchronized at version 7.13.4 and MongoDB 7.0.

• Binary Swap:
  • Updated the MongoDB container image from 5.0 to 6.0, then eventually to 7.0.
  • FCV 6.0:
    • Before moving to 7, we ensured the internal compatibility was set to 6.0:
      • db.adminCommand({setFeatureCompatibilityVersion: "6.0"})
• Pinned App:
  • Changed the Unraid template to rocket.chat:7 (currently at 7.13.4).
• Verified Backup:
  • Performed the mongodump and a “Gold Standard” restore test to a separate MongoTest container (65,486 documents confirmed).
• FCV 7.0:
  • Finalized the database upgrade with the mandatory confirmation:
  • db.adminCommand({setFeatureCompatibilityVersion: "7.0", confirm: true})