Thousands of organizations are moving to Mattermost for powerful, flexible, and easy-to-manage workplace messaging. Mattermost deploys as a single Linux binary with MySQL or PostgreSQL and can scale from dozens to tens of thousands of users in a single channel.
This guide summarizes different approaches to migrating from one Mattermost deployment to another and migrating from other messengers (such as Slack, HipChat, Jabber, and bespoke solutions) to Mattermost.
- Migrating the Mattermost Server
- Migrating to Mattermost From Other Messaging Solutions
- Migrating From Bespoke Messaging Solutions to Mattermost
- Migrating from Slack
- Migrating from Bitnami
- Migrating from HipChat Server and HipChat Data Center to Mattermost
- Migrating from Jabber to Mattermost
- Migrating from Pidgin to Mattermost
The following instructions migrate Mattermost from one server to another by backing up and restoring the Mattermost database and
config.json file. For these instructions SOURCE refers to the Mattermost server from which your system will be migrated and DESTINATION refers to the Mattermost server to which your system will be migrated.
- Backup your SOURCE Mattermost server.
- See Backup Guide.
- Upgrade your SOURCE Mattermost server to the latest major build version.
- Install the latest major build of Mattermost server as your DESTINATION.
- See Installing Mattermost for install guides. Make sure your new instance is properly configured and tested. The database type (MySQL or PostgreSQL) and version of SOURCE and DESTINATION deployments need to match.
- Stop the DESTINATION server using
sudo stop mattermost, then backup the database and
- Migrate database from SOURCE to DESTINATION.
- Backup the database from the SOURCE Mattermost server and restore it in place of the database to which the DESTINATION server is connected.
config.jsonfrom SOURCE to DESTINATION.
- Copy of
config.jsonfile from SOURCE deployment to DESTINATION.
- Copy of
- If you use local storage (
FileSettings.DriverNameis set to
./datafrom SOURCE to DESTINATION.
- Copy the
./datadirectory from SOURCE deployment to DESTINATION.
- If you use a directory other than
./data, copy that directory instead.
- Copy the
- If you use local storage (
- Start the DESTINATION deployment.
sudo start mattermost.
- Open the System Console, make a minor change, and save it to upgrade your
config.jsonschema to the latest version using default values for any new settings added.
- Test that the system is working by going to the URL of an existing team.
- You may need to refresh your Mattermost browser page in order to get the latest updates from the upgrade.
Once your migration is complete and verified, you can optionally upgrade the Team Edition of Mattermost to Enterprise Edition using the upgrade guide.
Many enterprises run bespoke, unsupported, lightly documented messaging systems driven by the initial excitement of the product’s promise.
Often the solutions were championed by tech-savvy early adopters who loved a few features and pushed out the solution broadly.
Over time, management moves to an IT team, where an unsupported solution becomes problematic to maintain and secure. Mattermost is often selected to replace bespoke solutions by IT and DevOps teams as a stable, enterprise-grade, commercially supported solution on an open source platform that meets and exceeds the flexibility and innovation of bespoke solutions.
Because messaging solutions in technical teams often contain confidential and highly exploitable data, messaging solutions become a security concern that could impact all of an organization’s technical infrastructure.
When IT teams are asked to maintain a bespoke messaging solution, they often need to consider security issues such as the following:
- Is the solution backed by a commercial entity with significant legal obligations to ensure the safety and security of the product?
- Is there a security bulletin available to alert our organization of high-priority security updates, with clear instructions to apply the updates?
- Does the solution have a clear and up-to-date list of security updates?
- Are security updates released prior to detailed disclosure of vulnerability details, so as to provide our organization with time to apply security updates before vulnerabilities are widely known?
- In addition to internal testing, is there a Responsible Disclosure Policy for external security researchers to confidentially report security issues, and a recognition program for their contributions?
Bespoke communication products that provide weak security assurance can dramatically increase the risk to IT teams and their organizations.
When early adopters of a bespoke solutions ask IT to “take over” and assume the risk of managing a rapidly installed, difficult-to-maintain system with limited or no assurance of security, the IT team is under a great deal of pressure.
Often at this point, IT teams accelerate their exploration of Mattermost as a long-term solution, given the thousands of organizations (many in mission critical, high security industries) that have switched.
Mattermost is designed to replace bespoke messaging solutions through a platform that is unmatched in flexibility. From the hundreds of open source projects extending and customizing Mattermost through APIs and drivers, to an innovative client and server plugin framework for adapting the Mattermost user experience to the specific workflows and needs, thousands of high performance teams rely on Mattermost daily.
In addition, IT teams prefer Mattermost for its specific security assurances:
- Mattermost products are backed by Mattermost, Inc., which has commercial contracts with hundreds of enterprises around the world, many with Fortune 500 and Global 2000 organizations who require significant obligations and assurances from vendors of critical infrastructure.
- Mattermost offers a security bulletin to alert IT teams and customers of high priority security updates, with step-by-step instructions for upgrade and options for commercial support.
- Mattermost maintains an up-to-date list of security updates for both its open source and commercial offerings.
- To keep IT teams safe, Mattermost waits 14 days after releasing a security patch before disclosing the specific details of the vulnerability each addresses.
- A Responsible Disclosure Policy is available to supplement internal security reviews with confidential reports from external security researchers, with a recognition program for security research contributions after the security patch is properly released.
Migrating from bespoke messengers to Mattermost can be challenging. Because of the difficulty of upgrading and maintaining bespoke solutions, the format for storing data is unpredictable, and the community around any single legacy release is small.
If your data in the bespoke messenger is vital, consider:
- Mattermost Bulk Load Tool - Use the Mattermost bulk load tool to ETL from your bespoke system to Mattermost.
- Mattermost ETL framework from BrightScout- Consider the Mattermost ETL framework from BrightScout to custom-configure an adapter to plug in to the Bulk Load tool mentioned above.
- Legacy Slack import - If you only recently switched from Slack to a bespoke tool, consider going back to import the data and users from the old Slack instance directly into Mattermost, leveraging the extensive support for Slack-import provided.
- Export to Slack, then import to Mattermost - Export HipChat, Flowdock, Campfire, Chatwork, Hall or CSV files to Slack and then export to a Slack export file and import the file into Mattermost.
If your data in the bespoke messenger is not vital, consider:
- Parallel systems - Running Mattermost in parallel with your bespoke system until the majority of workflow and collaboration has moved to Mattermost
- Hard switch - Announce a “hard switch” to Mattermost after a period of time of running both systems in parallel. Often this has been done due to security concerns in bespoke products or products nearing end-of-life.
Sometimes systems running in parallel turn into a hard switch migration when a bespoke or deprecated system experiences a major outage or a security exploit. In 2017, this was experienced by many companies using Mattermost and HipChat.com in parallel when HipChat suffered a major security breach where customer data was stolen by an unknown attacker.
When IT adopts management of Mattermost, often they will purchase the commercial version for additional compliance, access control, and scale features, in addition to high quality commercial support for upgrades and migrations. Teams can purchase Mattermost Enterpise Edition with a credit card online or contact sales to engage in an enterprise procurement process.
Slack offers two ways to export your data from their product.
- A Slack export file can be generated from Slack > Administration > Workspace settings > Import/Export Data > Export > Start Export. This export does not include private channels, direct, or group messages.
- You can request a “Corporate Export” from Slack directly to get a larger export including private channels, direct, and group messages.
As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. If you encounter issues not mentioned in the documentation below, please alert the product team by filing an issue.
The Slack Import feature in Mattermost is in Beta and focused on supporting migration of teams of less than 100 registered users. This feature can be accessed through the Mattermost Web App or using the CLI.
It is highly recommended that you test Slack import before applying it to an instance intended for production.
If you use Docker, you can spin up a test instance in one line:
docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
If you don’t use Docker, there are step-by-step instructions to install Mattermost in preview mode in less than 5 minutes.
The following key features can be imported from Slack:
- User accounts
- Public and private channels and the text messages posted in them, with formatting
- Channel topic and purpose
- Imported users added automatically to their channels
- Messages and message threads
- Direct and group messages
Messages with file attachments are imported as a message containing a link to Slack’s servers by default. The file attachments themselves can be imported to Mattermost by using the Slack Advanced Exporter tool to add them to your archive before importing it.
Bot and Integration messages are imported by default, but if you would like them to display with the appropriate username when imported, you should ensure that Enable Integrations to Override Usernames is set in System Console > Integrations > Integration Management (or System Console > Integrations > Custom Integrations in versions prior to 5.12) before doing the import.
When topic-change messages, purpose-change messages, and channel name-change messages are imported from Slack, they appear in Mattermost as posts from the System user.
Slack user accounts with the same email address as existing accounts on your Mattermost server will be merged into those accounts on import.
The following limitations are present when importing from Slack:
- The import is not idempotent, which means that duplicate posts are created if you import the same data more than once.
- Slack does not include direct or group messages and private channel messages when generating the export archive from their export tool. You will need to request a Corporate Export from them to access this data.
- If the handle of an imported Slack channel is the same handle as a deleted Mattermost channel, then a random handle is generated for the imported Slack channel.
- Pinned posts are not currently supported.
- Deleted users in Slack are currently not supported. They should be re-added to the file prior to import. Mattermost will be providing a fix for this in the near future.
For larger imports, particularly those where you have used the slack-advanced-exporter tool to add Slack post attachments to the archive or the Corporate Export file, it is recommended to import the Slack data using the mmetl tool and bulk loading tool.
- Generate a Slack export file from Slack > Administration > Workspace Settings > Import/Export Data > Export > Start Export. Alternatively, use the Slack Corporate Export file after receiving it from Slack.
- In Mattermost go to Team Settings > Import > Import from Slack. Team Admin or System Admin permission is required to access this menu option.
- Click Select file to upload Slack export file and click Import.
Generate a Slack export file from Slack > Administration > Workspace Settings > Import/Export Data > Export > Start Export.
Run the following Mattermost CLI command, with the name of a team you have already created:
$ mattermost import slack team_name /path/to/your-slack-export.zip
To run the CLI command, you must be in the directory that contains the Mattermost installation. On a default installation of Mattermost, the directory is
/opt/mattermost/. Also, if you followed our installation process, you must run the command as the user mattermost. The executable is in the
bin subdirectory and is called
This method is the recommended way to import Slack’s corporate export file.
- Use the slack-advanced-exporter to download attachments and add users’ email addresses to your Slack corporate export file.
- Use the mmetl tool to transform Slack’s corporate export file into the
jsonlformat required by the bulk import tool.
- Bulk load the files using the steps provided in the bulk loading documentation.
- During the import process, the emails and usernames from Slack are used to create new Mattermost accounts. If emails are not present in the Slack export archive, then placeholder values will be generated and the System Admin will need to update these manually.
- Slack users can activate their new Mattermost accounts by using Mattermost’s Password Reset screen with their email addresses from Slack to set new passwords for their Mattermost accounts.
- Once logged in, Mattermost users will have access to previous Slack messages in the public channels imported from Slack.
Bitnami uses MySQL, and renames the Mattermost database tables by converting the names to all lower case. For example, in non-Bitnami installations, the Users table is named “Users”, but in Bitnami, the table is “users”. As a result, when you migrate your data from Bitnami to a non-Bitnami installation, you must modify the MySQL startup script so that it starts MySQL in lowercase table mode.
You can modify the script by adding the
--lower-case-table-names=1 switch to the MySQL start command. The location of the start-up script generally depends on how you installed MySQL, whether by using the package manager for the operating system, or by manually installing MySQL. You must modify the start-up script before migrating the data.
For more information about letter case in MySQL table names and the
--lower-case-table-names switch, see the Identifier Case Sensitivity topic in the MySQL documentation.
Please see HipChat Migration Guide.
BrightScout helped a major U.S. Federal Agency rapidly migrate from Jabber to Mattermost and open sourced their Extract, Transform and Load (ETL) tool at https://github.com/Brightscout/mattermost-etl.
Read more about their case study online.
In some cases people are using Pidgin clients with different backends to communicate. To continue using Pidgin with a Mattermost backend consider using Mattermost ETL tool created by BrightScout to migrate data from your existing backend into Mattermost, then use the Pidgin-Mattermost plugin (complete with an installer for end-user machines) to continue to support legacy Pidgin users while offering a whole new Mattermost experience on web, mobile, and PCs.