Migrating from Self-hosted Mattermost Instance to Cloud Mattermost Instance

Before you begin your migration

Ensure you’re on Mattermost version 6.7 (or later) as this contains the latest version of the server and the mmctl tool which is used to perform the export.

You also need to take note of the following information before you begin your migration:

User Authentication

If you’re using a login method other than email, you’ll need to make the required changes to your infrastructure so that you can continue your existing authentication method in the cloud. Examples of these methods are LDAP and GitLab SSO.

Plugins

If you’re using plugins that aren’t listed on the Marketplace, they won’t be included in the export and you won’t have access to them going forward. You can view a list of our current marketplace plugins here

Data

The migration only includes data from Channels. No Boards or Playbooks data is exported.

Migration process

Export from your self-hosted instance

Use your administrator credentials to log into your self-hosted Mattermost server. Once you're logged in, run:

$ mmctl export create --attachments

This creates a full export of the server, and includes attached files. If you don’t want to export attached files, leave out --attachments.

This process can take some time, so mmctl will return immediately, and the job will run in the background until the export is fully created. If successful, the command will immediately output a job ID, like this:

Export process job successfully created, ID: yfrr9ku5i7fjubeshs1ksrknzc

While the job is running, its status can be checked using the ID that was provided when it was created, and when it's done the output will look similar to this:

$ mmctl export job show yfrr9ku5i7fjubeshs1ksrknzc

ID: yfrr9ku5i7fjubeshs1ksrknzc

Status: success

Created: 2021-11-03 10:44:13 -0500 CDT

Started: 2021-11-03 10:44:23 -0500 CDT

The completed file will be downloaded to your desktop as a .zip file.

Test your export

To cut down on complications with corrupt exports you will need to import your export into a new local Mattermost instance. This is needed so that we can verify that the import will successfully finish and so we can work out any potential errors ahead of the cloud import. 

With the export file you can follow the documentation here to import your export file to this second instance.  If there are no errors you can contact Support and they will provide you with S3 credentials so you can upload the exported file. Once you’ve uploaded the file, please contact the Support team to continue the process.

NOTE: You do not need additional licensing for this step 

Create a new workspace on the Mattermost Cloud

In the meantime, you can log into Mattermost Cloud with your Mattermost credentials and create a Cloud workspace. 

Importing your data into your Mattermost Cloud instance

Once the export upload to the provided S3 bucket is complete and you’ve shared your Mattermost Cloud instance name/URL, Support can begin the import step.

Depending on the size of the export this process can take some time. Support will contact you as soon as the import is complete. During this time it is highly recommended you do not use your Mattermost Cloud instance.

Start using your Mattermost Cloud instance

When the export is complete, you can log into your Cloud instance and can invite your users to log in.