Migrate from mmap to WiredTiger Storage Engine

Starting with the major release 4.x of Rocket.Chat, MongoDB has to be set up with a WiredTiger storage engine rather than the deprecated mmapv1 one. This is mandatory, if you plan to upgrade to one of the future Rocket.Chat versions have to be prepared before initiating the application upgrade.

This guide helps you migrate your existing mmap based MongoDB instance to WiredTiger manually.


  • MongoDB instance with mmap storage engine.

Quick usage

Following is an overview of the migration steps:

  1. Stop running Rocket.Chat.

  2. Create a database dump from the mmapv1 MongoDB (also to have a backup in place).

  3. Stop mmapv1 MongoDB service, drop existing data files, and start up with WiredTiger.

  4. Import the dump into the new WiredTiger MongoDB.

  5. Start Rocket.Chat.

Detailed usage

Here are the detailed steps of the migration process:

  1. Stop Rocket.Chat service to ensure a consistent database dump:

    systemctl stop rocketchat
  2. Create a database dump from the current mmapv1 MongoDB:

    mongodump --archive=~/mmapdump.gz --gzip
  3. Stop MongoDB service:

    systemctl stop mongod
  4. Delete the mmapv1 based data files of your existing MongoDB:

    rm -rf /var/lib/mongodb/*
  5. Adjust MongoDB configuration to make use of wiredTiger storage engine:

    vi /etc/mongod.conf
    engine: wiredTiger
  6. Start MongoDB service again:

    systemctl start mongod
  7. If running with a Replica-Set in your mongo.conf initialize replica set

    mongo --eval 'rs.initiate()'
  8. Import dump back into (wiredTiger) MongoDB:

    mongorestore --drop --archive=~/mmapdump.gz --gzip --noIndexRestore
  9. Repair databases and rebuild indices:

    mongo --eval 'db.repairDatabase()'
  10. Start Rocket.Chat service:

    systemctl start rocketchat

Last updated

Rocket.Chat versions receive support for six months after release.