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.