Migrating Rocket.Chat to Mattermost on a VPS

What changes in Rocket.Chat 9.0

Why Mattermost Community is a solid alternative

• LDAP and SAML included without a license — Mattermost ships Active Directory and SAML authentication in its open source edition, under MIT license for the server (Apache 2.0 for contributions), with no plan requirement.
• Native PostgreSQL — Mattermost relies on PostgreSQL, well-documented, easy to back up with pg_dump and more common than MongoDB in self-hosted Docker environments.
• mmetl, an official migration tool — the mmetl tool from the Mattermost team transforms a Rocket.Chat mongodump into a JSONL import file compatible with mmctl import, including channels, users and messages.
• Lower memory footprint — Mattermost can start with 2 GB of RAM for teams of fewer than fifty users; Rocket.Chat requires a MongoDB replica set that consumes more at equivalent volume.
• Official desktop and mobile apps — iOS, Android, macOS and Windows clients point to your own domain from installation.
• Full message history, no storage quota — no sliding window, no message volume cutoff, everything is stored on your disk or S3 bucket.

Measured prerequisites

Back up Rocket.Chat

1. 01

   Put Rocket.Chat in read-only mode

   Before any backup, notify your users and put the instance in maintenance mode. In Rocket.Chat administration, go to Administration → General → Maintenance mode and enable read-only mode. This prevents messages from being written after the dump and lost at cutover.

   Alternatively, if you do not have this mode, simply stop the Rocket.Chat container:

   docker compose stop rocketchat

2. 02

   Export the MongoDB database with mongodump

   mmetl expects a directory produced by mongodump, not a compressed file. Run the dump from the host or from inside the MongoDB container:

   # from the host, if mongodump is installed
   mongodump --uri="mongodb://localhost:27017/rocketchat" --out /tmp/rc-dump
   
   # or from the Docker container
   docker exec <mongo-container> mongodump \
     --db rocketchat --out /dump
   docker cp <mongo-container>:/dump /tmp/rc-dump

   Verify that /tmp/rc-dump/rocketchat/ contains .bson and .json files for the rocketchat_message, users, rocketchat_room collections, etc.

3. 03

   Export file attachments (uploads)

   File attachments stored in GridFS or the local filesystem are not part of the MongoDB dump — they must be copied separately.

   If you use local storage (default option):

   docker cp <rocketchat-container>:/app/uploads /tmp/rc-uploads

   If you use an S3-compatible bucket, note the connection parameters — you will reconfigure them in Mattermost. mmetl references file attachments but does not transfer them: you will push them manually or via mmctl import with the --attachments-dir option.

4. 04

   Export users via REST API (optional)

   For an inventory of accounts before migration, the Rocket.Chat API can export the list of active users. This facilitates cross-checking after the Mattermost import:

   curl -H "X-Auth-Token: <token>" \
        -H "X-User-Id: <admin-id>" \
        "https://chat.yourdomain.com/api/v1/users.list?count=200" \
     | python3 -c "import sys,json; [print(u['username'], u.get('emails',[{}])[0].get('address','')) for u in json.load(sys.stdin)['users']]"

   Keep this list: it serves to verify that all accounts are correctly created in Mattermost after bulk import.

Install Mattermost on your VPS

1. 05

   Get the official Docker Compose configuration

   The Mattermost team maintains a docker repository with a ready-to-use Compose configuration:

   git clone https://github.com/mattermost/docker /opt/mattermost
   cd /opt/mattermost
   cp env.example .env

   Open .env and fill in at minimum:

   DOMAIN=chat.yourdomain.com
   MM_SERVICESETTINGS_SITEURL=https://chat.yourdomain.com
   POSTGRES_USER=mmuser
   POSTGRES_PASSWORD=<strong-password>
   POSTGRES_DB=mattermost

2. 06

   Create volumes and start the stack

   Create volume directories before the first startup:

   mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
   sudo chown -R 2000:2000 ./volumes/app/mattermost

   Start the full stack (Mattermost + PostgreSQL + nginx with integrated Let's Encrypt certificate):

   docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d

   Wait for the Mattermost container to be healthy before continuing:

   docker compose ps

3. 07

   Create the administrator account

   Open https://chat.yourdomain.com in your browser. On first login, Mattermost prompts for the creation of an admin account. Enter the email, username and password for the initial administrator — this account will be separate from accounts imported from Rocket.Chat.

   Once logged in, go to System Console → Environment → Site URL and verify the URL matches exactly what was declared in .env.

Migrate history and users with mmetl

1. 08

   Install mmetl

   Download the mmetl v0.6.0 binary (released September 11, 2026) from GitHub releases:

   curl -L https://github.com/mattermost/mmetl/releases/download/v0.6.0/mmetl-linux-amd64 \
     -o /usr/local/bin/mmetl
   chmod +x /usr/local/bin/mmetl
   mmetl version

   Breaking change in v0.6.0: the mmetl check subcommand has been removed. Use mmetl transform ... --dry-run to validate the dump before producing the import file.

2. 09

   Transform the Rocket.Chat dump into a Mattermost import file

   Run the transformation pointing to the directory containing the BSON collections exported (the rocketchat subfolder of the dump) and the target Mattermost team name:

   mmetl transform rocketchat \
     --team my-team \
     --dump-dir /tmp/rc-dump/rocketchat \
     --output /tmp/mattermost-import

   mmetl generates an import.jsonl file and a bulk-export-attachments/ directory. To test without generating output:

   mmetl transform rocketchat \
     --team my-team \
     --dump-dir /tmp/rc-dump/rocketchat \
     --dry-run

   Check warnings: messages from private channels without a recognized member are skipped; attachments absent from the uploads directory are referenced but not transferred.

3. 10

   Run the import in Mattermost via mmctl

   Copy the import file into the Mattermost data directory, then run the bulk import:

   # copy into the container
   docker cp /tmp/mattermost-import/import.jsonl \
     <mattermost-container>:/mattermost/data/import.jsonl
   
   # run import from mmctl (inside the container)
   docker exec <mattermost-container> mmctl import bulk \
     /mattermost/data/import.jsonl --bypass-upload

   To track progress, check import jobs in System Console → Bulk Import. Errors are logged line by line — a partial import does not block the rest.

4. 11

   Verify results and known limitations

   After the import, check the following points:
   - Public and private channels should be present in Mattermost with their history.
   - Usernames are imported but passwords are not — each user must reset their password or log in via LDAP if the directory is configured.
   - File attachments require a second pass with --attachments-dir pointing to the directory copied from Rocket.Chat.
   - Discussion threads (nested replies) are flattened if the structure is not recognized.

Configure LDAP in Mattermost Community

1. 12

   Enable LDAP in the System Console

   In System Console → Authentication → AD/LDAP, enable LDAP and fill in the connection parameters:

   LDAP Server: ldap.yourdomain.com (or your domain controller IP)
   Port: 389 (LDAP) or 636 (LDAPS)
   Bind Username: cn=mattermost-svc,ou=serviceaccounts,dc=yourdomain,dc=com
   Bind Password: <service-account-password>
   Base DN: ou=users,dc=yourdomain,dc=com

   Enable LDAP over TLS (LDAPS) or StartTLS if your infrastructure supports it — do not transmit credentials in clear text over an unencrypted network.

2. 13

   Configure attribute mappings

   Mattermost reads LDAP attributes to populate profiles. Common mappings for Active Directory:

   ID Attribute:        objectGUID  (or sAMAccountName if GUID is unavailable)
   Username Attribute:  sAMAccountName
   Email Attribute:     mail
   First Name:          givenName
   Last Name:           sn

   For OpenLDAP, replace sAMAccountName with uid and objectGUID with entryUUID.

   In User Filter, restrict synchronization to members of the desired group:

   (memberOf=cn=mattermost-users,ou=groups,dc=yourdomain,dc=com)

3. 14

   Test the connection and synchronize

   Click AD/LDAP Test at the bottom of the page to validate the connection and bind. If you get LDAP Result Code 49 'Invalid Credentials', check the service account DN and password.

   Trigger a first manual synchronization via AD/LDAP Synchronize Now. Users whose email attribute matches an account already imported via mmetl will be linked automatically — they will then log in with their LDAP credentials without resetting their password.

Common troubleshooting

ldapsearch -x -H ldap://ldap.yourdomain.com \
  -D "cn=mattermost-svc,ou=serviceaccounts,dc=yourdomain,dc=com" \
  -W -b "ou=users,dc=yourdomain,dc=com" "(uid=testuser)"

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Rocket.Chat Community 9.0 vs Mattermost Community

Scroll the table

Mattermost Community, a stable long-term platform