Mattermost Recipe: Migrating a Mattermost Server with `mmctl`

Problem

You want to move your Mattermost data from one Mattermost server to another, including files, but can’t back up your database and files directly.

Solution

Note: These instructions are for Mattermost v5.36.1 and higher. Please upgrade your Mattermost instance if you are running an older version.

0. Set up your destination server

Install Mattermost and create a single Mattermost user as admin. Go to the System Console and configure it as necessary for your application. Instructions for installing Mattermost Server are available in our documentation

1. Install mmctl

There are installation instructions on mmctl’s Github page or you can use the versionmmctl is currently packaged with the server release as a Linux binary. If you followed our standard installation instructions it will be located at /opt/mattermost/bin/mmctl on your new server.

2. Set up Authentication for the source server

You Will Need

  • The URL of the Mattermost server you are exporting from. This will look like https://mattermost-source.example.com
  • The username and password for an username authenticated system administrator user
mmctl auth login https://mattermost-source.example.com/

Replace https://mattermost-source.example.com with the URL of your Mattermost server. You will be asked for a profile name and a username and password.

If you would like to use Access Tokens, because you are using SAML or OpenID authentication, generate one with system administrator rights and run this command:

mmctl auth login https://mattermost.example.com/ --name mmst_source --access-token <YOUR ACCESS TOKEN>

Replace <YOUR ACCESS TOKEN> with the access token you generated.

Then, be sure to set this profile with this command:

mmctl auth set mmst_source

3. Start the export job

Run this command to start the bulk export job:

mmctl export create --attachments

Note Be sure to include the --attachments flag to include file attachments in your export. If you have a large number of files you should remove it so that

This will export all users, teams, channels, and direct and group messages in the Mattermost Server.

Record the returned export job ID:

Export process job successfully created, ID: oademxrchpnpirj1yduhg8xm5c

4. Monitor the export job

Run mmctl export job list to monitor the status of the job you started:

mmctl export job list

When the job is done it will have Status: success:

  ID: oademxrchpnpirj1yduhg8xm5c
  Status: success
  Created: 2021-07-12 12:59:23 -0400 EDT
  Started: 2021-07-12 12:59:36 -0400 EDT

5. Download the export

First, run mmctl export list to show the export files available for download. Record the returned filename:

i5xxc65nfinsxb4zjq4tbdh4he_export.zip

Then, download the export with this command:

mmctl export download i5xxc65nfinsxb4zjq4tbdh4he_export.zip

Replace i5xxc65nfinsxb4zjq4tbdh4he_export.zip with the name of the export file.

The export

6. Authenticate with the destination server

Repeat step 1 but use the URL of your destination Mattermost server, e.g.

mmctl auth login https://mattermost2.example.com/

Then, be sure to set this authentication profile with this command:

mmctl auth set mmst_dest

Change mmst_dest to the profile name you chose for the destination server.

7. Upload the import file:

Run this command to upload the file:

mmctl import upload i5xxc65nfinsxb4zjq4tbdh4he_export.zip

Replace i5xxc65nfinsxb4zjq4tbdh4he_export.zip with the name of your export file.

Sample Output:

Upload session successfully created, ID: bu4nwie39bfrmdwz8wmefyyhzc 
Import file successfully uploaded, name: jfgpx1up4ffabf5ws8jfrcwpuh

8. Verify the file upload

Run mmctl import list available to show the imports available:

bu4nwie39bfrmdwz8wmefyyhzc_i5xxc65nfinsxb4zjq4tbdh4he_export.zip

9. Run the Import Job

Run this command to start the import job:

mmctl import process bu4nwie39bfrmdwz8wmefyyhzc_i5xxc65nfinsxb4zjq4tbdh4he_export.zip

Then run mmctl import job list to view the status of the import:

  ID: k5nefu3zpj86by8rxi3xaxk3sr
  Status: success
  Created: 2021-07-12 14:33:31 -0400 EDT
  Started: 2021-07-12 14:33:44 -0400 EDT

When it say success the import is complete.

10. Verify the data

Go to these locations in the System Console to verify the data was imported correctly:

  • Teams
  • Channels
  • Users

Then, switch to one of the teams and browse the channels to make sure everything was imported as expected.

Discussion

While this seems like a lot of steps this is much faster and easier than it used to be. And because you’re using mmctl it can work from any machine that has access to both Mattermost servers.

Since we’ll be deprecating the traditional CLI tool - RIP /opt/mattermost/bin/mattermost - all Mattermost administrators should install mmctl. Besides making exports easy, it also lets you create users, reset passwords, and manage teams and channels from the command line or in scripts. Once it’s installed, just type mmctl help and it will give you all the available options.

If you’d like to migrate from Slack, we have the mmetl tool to convert it into the Mattermost bulk export format, which can be uploaded following the steps 6-10 above. More information is available on Github and in our documentation.

7 Likes

Great recipe! IMHO, should be moved to the official documentation.

1 Like