240db4e2a7
Some checks failed
Server CI / Postgres (shard 0) (push) Has been skipped
Server CI / Postgres (shard 3) (push) Has been skipped
BuildEnv Docker Image / build-image (push) Failing after 4s
BuildEnv Docker Image / build-image-fips (push) Failing after 4s
Migration Review & Release Notes / Generate migration review & release notes (push) Failing after 3s
Server CI / Build Environment (push) Failing after 3s
Server CI / Postgres (shard 1) (push) Has been skipped
Tools CI / check-style (mattermost-govet) (push) Failing after 4s
Server CI / Postgres (shard 2) (push) Has been skipped
Tools CI / check-style (mmgotool) (push) Failing after 3s
Server CI / Elasticsearch v8 Compatibility (push) Has been skipped
Server CI / OpenSearch v2 Compatibility (push) Has been skipped
Server CI / Postgres FIPS (shard 0) (push) Has been skipped
Tools CI / Test (mattermost-govet) (push) Failing after 3s
Server CI / Postgres FIPS (shard 1) (push) Has been skipped
Server CI / Postgres FIPS (shard 2) (push) Has been skipped
Tools CI / Test (mmgotool) (push) Failing after 3s
Server CI / Postgres FIPS (shard 3) (push) Has been skipped
Server CI / Run mmctl tests (push) Has been skipped
Server CI / Run mmctl tests (FIPS) (push) Has been skipped
Server CI / Merge Postgres Test Results (push) Has been skipped
Server CI / Merge Postgres FIPS Test Results (push) Has been skipped
Server CI / Check backport migrations (push) Has been skipped
Server CI / Check generated files (push) Has been skipped
Server CI / check-style (push) Has been skipped
Server CI / Vet API (push) Has been skipped
Server CI / Build mattermost server app (push) Has been skipped
Server CI / Server CI Complete (push) Failing after 2s
Server CI / Server CI Artifacts (push) Has been skipped
Server CI / Sentry Upload (push) Has been skipped
Server CI / Server CI Report (push) Failing after 5m1s
Server CI Nightly Race / Race Detector (push) Has been skipped
CodeQL / Analyze (go) (push) Has been cancelled
CodeQL / Analyze (javascript) (push) Has been cancelled
Webapp CI Cache Warm / Warm Webapp node_modules Cache (push) Has been cancelled
E2E CI Cache Warm / Warm E2E npm Registry Cache (push) Has been cancelled
API / build (push) Has been cancelled
Web App CI / check-types (push) Has been cancelled
Web App CI / check-lint (push) Has been cancelled
Web App CI / check-i18n (push) Has been cancelled
Web App CI / check-external-links (push) Has been cancelled
Web App CI / test (platform) (push) Has been cancelled
Web App CI / test (mattermost-redux) (push) Has been cancelled
Web App CI / test (channels shard 1/4) (push) Has been cancelled
Web App CI / test (channels shard 2/4) (push) Has been cancelled
Web App CI / test (channels shard 3/4) (push) Has been cancelled
Web App CI / test (channels shard 4/4) (push) Has been cancelled
Web App CI / upload-coverage (push) Has been cancelled
Web App CI / build (push) Has been cancelled
YAML Lint / yamllint (push) Has been cancelled
Push mirrored docker images / cd/Push mirrored docker images (push) Has been cancelled
docs-cd / Build and deploy docs (push) Has been cancelled
Docs CI / build (push) Has been cancelled
E2E Cache Warm: Cypress deps / Warm Cypress deps cache (push) Has been cancelled
Scorecards supply-chain security / Scorecard analysis (push) Has been cancelled
Server CI Weekly / Postgres FIPS (push) Has been skipped
Server CI Weekly / Run mmctl tests (FIPS) (push) Has been skipped
Server CI Weekly / Postgres with binary parameters (push) Has been skipped
Server CI Weekly / Build Environment (push) Failing after 1s
Server CI Cache Warm / Warm Go Module and Build Cache (push) Failing after 2s
Server CI Nightly Race / Build Environment (push) Failing after 1s
78 lines
7.7 KiB
Plaintext
78 lines
7.7 KiB
Plaintext
---
|
||
title: "Migration guide"
|
||
---
|
||
<PlanAvailability slug="all-commercial" />
|
||
|
||
Migrations help you move your Mattermost deployment or data from one environment to another with minimal disruption. Whether you’re transitioning your Mattermost server to new infrastructure, restructuring your database, or moving from another collaboration platform like Slack, this guide provides step-by-step instructions for each supported path. Use the sections below to quickly find the scenario that matches your needs and follow the recommended process to ensure a smooth migration.
|
||
|
||
To change the database or container images an existing deployment runs on, see [data export and infrastructure migration](/administration-guide/manage/admin/migration) instead.
|
||
|
||
[Book a live demo](https://mattermost.com/request-demo/) or [talk to a Mattermost expert](https://mattermost.com/contact-sales/) to explore tailored solutions for your organization's secure collaboration needs. Or try Mattermost yourself with a [1-hour preview](https://mattermost.com/sign-up/) for instant access to a live sandbox environment.
|
||
|
||
## Move Mattermost to a new server
|
||
|
||
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.
|
||
|
||
1. Back up your SOURCE Mattermost server. See [Backup and Disaster Recovery documentation](/deployment-guide/backup-disaster-recovery).
|
||
2. Upgrade your SOURCE Mattermost server to the latest major build version. See [Upgrading Mattermost Server documentation](/administration-guide/upgrade/upgrading-mattermost-server).
|
||
3. Install the latest major build of Mattermost server as your `DESTINATION`.
|
||
|
||
> - 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 back up the database and `config.json` file.
|
||
|
||
4. 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.
|
||
5. Migrate `config.json` from `SOURCE` to `DESTINATION`. Copy `config.json` file from `SOURCE` deployment to `DESTINATION`.
|
||
6. If you use local storage (`FileSettings.DriverName` is set to `local`), migrate `./data` from `SOURCE` to `DESTINATION`.
|
||
|
||
> - Copy the `./data` directory from `SOURCE` deployment to `DESTINATION`.
|
||
> - If you use a directory other than `./data`, copy that directory instead.
|
||
|
||
7. Start the `DESTINATION` deployment by running `sudo start mattermost`. Then go to the **System Console**, make a minor change, and save it to upgrade your `config.json` schema to the latest version using default values for any new settings added.
|
||
8. 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](/administration-guide/upgrade/upgrading-mattermost-server#upgrade-team-edition-to-enterprise-edition).
|
||
|
||
## Move from Slack
|
||
|
||
See the [Migrate from Slack](/administration-guide/onboard/migrate-from-slack) documentation for details on migrating from Slack to Mattermost.
|
||
|
||
## Move from Rocket.Chat
|
||
|
||
See the [Migrate from Rocket.Chat](/administration-guide/onboard/migrate-from-rocketchat) documentation for details on migrating from Rocket.Chat to Mattermost.
|
||
|
||
## Move from Jabber
|
||
|
||
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](https://github.com/Brightscout/mattermost-etl). Read more about their [case study](https://mattermost.com/blog/u-s-federal-agency-migrates-from-jabber-to-mattermost-the-open-source-way/) online.
|
||
|
||
## Move from Pidgin
|
||
|
||
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](https://github.com/Brightscout/mattermost-etl), created by BrightScout, to migrate data from your existing backend into Mattermost.
|
||
|
||
Then use the [Pidgin-Mattermost plugin](https://github.com/EionRobb/purple-mattermost) (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 PC.
|
||
|
||
## Move from Bitnami
|
||
|
||
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` (with a lowercase `u`). 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](https://dev.mysql.com/doc/refman/5.7/en/identifier-case-sensitivity.html) topic in the MySQL documentation.
|
||
|
||
## Move from bespoke messaging solutions
|
||
|
||
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.
|
||
|
||
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:
|
||
|
||
1. [Mattermost bulk import tool](/administration-guide/onboard/bulk-loading-data): Use the Mattermost bulk import tool to ETL from your bespoke system to Mattermost.
|
||
2. [Mattermost ETL framework from BrightScout](https://github.com/Brightscout/mattermost-etl): Consider the Mattermost ETL framework from BrightScout to custom-configure an adapter to plug in to the bulk import tool mentioned above.
|
||
3. **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.
|
||
4. **Export to Slack, then import to Mattermost:** [Export Flowdock, Campfire, Chatwork, Hall, or CSV files to Slack](https://slack.com/help/articles/217872578-Import-data-from-one-Slack-workspace-to-another) 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:
|
||
|
||
1. **Parallel systems:** Running Mattermost in parallel with your bespoke system until the majority of workflow and collaboration has moved to Mattermost
|
||
2. **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.
|