diff --git a/source/administration-guide/onboard/migrate-from-slack.rst b/source/administration-guide/onboard/migrate-from-slack.rst index 61a17784970..3fbec629b5a 100644 --- a/source/administration-guide/onboard/migrate-from-slack.rst +++ b/source/administration-guide/onboard/migrate-from-slack.rst @@ -4,29 +4,112 @@ Migrate from Slack .. include:: ../../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: +Overview +-------- + +Migrating from Slack to Mattermost is a multi-step process that can be complex, particularly for larger organizations or those with multiple Slack workspaces. The process generally involves preparing your environment, exporting data from Slack, converting that data into a compatible format, and then importing it into Mattermost. + +Additionally, please consider that Slack's data control policies or export capabilities may change at any time, or they may charge fees to customers for exporting data stored in Slack. Support for negotiating export of customer IP from Slack Enterprise can be requested by contacting a `Mattermost Expert `_. + +1. `Preparations <#preparations>`__: + + - Answer key scoping questions. + - Gather environment and export details. + - Validate Mattermost server capacity and configuration. + - Back up your Mattermost environment before importing. + +2. `Export Slack data <#export-slack-data>`__: + + - Generate an export from Slack in the user interface or by contacting Slack directly. + - Download file attachments and email addresses using the ``slack_advanced_exporter`` + +3. `Transform the export for Mattermost <#transform-the-export-for-mattermost>`__: + + - Use the ``mmetl`` tool to parse and transform Slack exports. + +4. `Import into Mattermost <#import-data-into-mattermost>`__: + + - Upload and process transformed archives with ``mmctl``. + +5. Validate and test: + + - Confirm channel and user data imported correctly. + - Run database queries to fix any unread states. + +6. Go live: + + - Communicate the cutover plan to users. + +Migration timeline +~~~~~~~~~~~~~~~~~~ + +These instructions outline a *best effort* migration path designed to preserve the majority of your messages, files, and workspace structure. Mattermost provides tools and guidance to help streamline the process, but manual adjustments during the data transformation and import steps are often required. Successful migration depends on careful planning and dedicating sufficient time, technical resources, and technical skills to the effort. + +Depending on the size and complexity of your Slack environment, a full migration can take anywhere from several days to multiple weeks of dedicated effort. Larger organizations with multiple workspaces, extensive message history, and many files should expect the process to require significant iteration and testing before completion. It’s important to plan for this timeline in advance by allocating the necessary resources, scheduling time for trial imports in a development environment, and coordinating across teams. Building in extra time for adjustments during the transformation and import steps will help ensure a smoother transition and reduce disruption to your users. + +Scoping the migration appropriately during the preparation step can significantly reduce processing time and allow for faster iteration. Before beginning, carefully consider what data is essential to bring over to Mattermost. Many organizations find that not every channel or file needs to be migrated, and focusing only on what is truly needed can save substantial processing time and manual effort. By setting clear boundaries early, you’ll minimize the amount of data that requires manual intervention and testing, which in turn shortens the migration timeline and helps avoid unnecessary complexity. + .. note:: + Consider `talking to a Mattermost expert `_ if your organization needs support migrating from Slack to Mattermost. + +Migrations Steps +---------------- + +.. _preparations: + +1. Preparations +~~~~~~~~~~~~~~~ + +Before beginning the migration, it’s important to properly prepare your environment. Careful preparation helps reduce processing time, allows for faster iteration, and minimizes the chance of running into avoidable issues during the import. + +This document assumes you already have a Mattermost Server deployed that is ready to accept your Slack data. If not, consider the recommendations in this section in conjunction with the appropriate :ref:`deployment documentation ` to make informed decisions about your supporting database and file storage infrastructure. + +Scope definition +^^^^^^^^^^^^^^^^ + +Start by defining the scope of your migration: + +- **Slack edition**: Migrating from Slack Enterprise Grid involves additional `steps and planning <#faq>`_. +- **Data history**: Decide how much history is necesary to import. Importing a smaller time window (e.g., the last six months) can significantly reduce complexity and processing time. +- **Export size**: Consider the size of your Slack export file as you progress through this guide. File size directly impacts how long the import will take - for example, files under ~25 GB often complete within a day, while exports over 100 GB can take several days, significantly lengthening the time between iterations and the overall timeline to complete the migration. +- **File attachments**: Consider whether you can exclude very large or non-critical attachments (for example, public software download packages, videos, or outdated media assets) to reduce import size and speed up processing. + +Infrastructure considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The environment where you run the import can significantly affect performance: + +- **Test environment**: Always run the migration in a development or staging environment first. Most migrations require multiple iterations before a production import is successful. +- **Operating system**: The ``mmetl`` and ``slack_advanced_exporter`` tools are supported on Linux and macOS. Windows is not supported, and we do not recommend using Windows Subsystem for Linux (WSL) since the file system is not performant enought for the heavier processes involved in migration. +- **Storage requirements**: Ensure your server can store both the Slack export archive and the fully unpacked data. As a best practice, plan for at least three times the size of your Slack export in available server storage. +- **File Storage**: Imports into S3 file storage typically complete faster than imports into MinIO. If using MinIO, you may want to consider increasing the number of volumes per server. + +Mattermost server considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - `Slack's data control policies may change at any time `_. Also, Slack may choose to change its export capabilities, and/or charge fees to customers for exporting data stored in Slack. Support for negotiating export of customer IP from Slack Enterprise can be requested by contacting a `Mattermost Expert `_. +Carefully preparing your environment and making these adjustments up front will help ensure the migration proceeds smoothly and reduces the need for repeated trial-and-error. -Migrating from Slack to Mattermost involves the following steps: +- **Fresh server**: The most reliable imports happen on a fresh Mattermost installation. If importing into an existing server, never import over an existing team. -1. `Prepare your Mattermost server <#prepare-your-mattermost-server>`__ -2. `Generate a Slack import <#generate-a-slack-import>`__ -3. `Download file attachments and email addresses <#download-file-attachments-and-email-addresses>`__ -4. `Convert the Slack import to Mattermost's format <#convert-slack-import-to-mattermost-s-bulk-export-format>`__ -5. `Import data into Mattermost <#import-data-into-mattermost>`__ +- **Server version**: Make sure you are running the latest supported version of :doc:`Mattermost ` to benefit from the most up-to-date functionality and fixes. -1. Prepare your Mattermost server ---------------------------------- +- **Backups**: When importing into an already existing Mattermost environment, back up both the Mattermost database and the data directory before starting. If an import fails, you’ll need to roll back or reset. -During the import process, we advise to create a new team for importing the Slack workspace data. If merging multiple Slack workspaces into a single team is the desired end-result, we recommend completing the import to separate teams, validating the results, then using :ref:`mmctl ` to move channels between teams. + - If merging multiple Slack workspaces into a single team is the desired end-result, we recommend completing the import to separate teams, validating the results, then using :ref:`mmctl ` to move channels between teams. -Also, system administrator roles will be overwritten if the usernames match and the user isn't an admin on the Slack workspace. +- **Configuration settings**: Adjust the following settings before starting the import: -Make sure you are running on a supported version of :doc:`Mattermost ` to benefit from the most up-to-date functionality and fixes. + - ``TeamSettings.MaxChannelsPerTeam``: Set to this to a number much higher than the number of users you are migrating. + - ``TeamSettings.MaxUsersPerTeam``: Set to this to a number much higher than the number of users you are migrating. + - **Team Settings > Allow any user with an account on this server to join this team**: Ensure this is enabled for the team receiving the import. + - ``EmailSettings.EnableSignUpWithEmail`` and ``EmailSettings.EnableSignInWithEmail``: Both must be set to ``true`` + - ``FileSettings.MaxFileSize``: Set this higher than the largest file in your Slack export. + - ``ElasticsearchSettings. EnableIndexing``, ``ElasticsearchSettings > EnableSearching`` and ``ElasticsearchSettings.EnableAutocomplete``: All must be set to ``false`` during the import to prevent performance issues. After the import, you can purge and reindex before enabling Elasticsearch. -2. Generate a Slack import --------------------------- +.. _export-slack-data: + +2. Export Slack data +~~~~~~~~~~~~~~~~~~~~ Slack offers two ways to `export your data from their product `_. @@ -47,10 +130,10 @@ You will receive a zip file containing the following contents: .. note:: - Refer to the `Slack help article `__ for additioanl details on zip file contents. - - 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 following documentation, please let the Mattermost Product Team know by `filing an issue `__. + - As a proprietary SaaS service, Slack is able to change its export format quickly and without notice. -3. Download file attachments and email addresses ------------------------------------------------- +Download file attachments and email addresses +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When you download your Slack export zip file, some data will be missing from the zip file: @@ -73,9 +156,9 @@ We need to create a Slack app in order to gather these contents. Follow these st 8. Grant the app permissions when prompted. 9. Copy the **Bot User OAuth Token** and save it somewhere convenient. -We'll now use **Bot User OAuth Token** with the ``slack-advanced-exporter`` tool to download emails and attachments. Download the latest release of ``slack-advanced-exporter`` for your OS and architecture `here `__ and extract the executable from the download. +We'll now use **Bot User OAuth Token** with the ``slack-advanced-exporter`` tool to download emails and attachments. Download the latest release of ``slack-advanced-exporter`` `for your OS and architecture `_ and extract the executable from the download. -Once you have the program downloaded locally, run the commands below to fetch the emails, and then fetch file attachments. Replace ```` with the Slack token you generated earlier and ```` with the `path `__ to your export file. +Once you have the program downloaded locally, run the commands below to fetch the emails, and then fetch file attachments. Replace ```` with the Slack token you generated earlier and ```` with the `path to your export file `_. .. code-block:: sh @@ -95,8 +178,10 @@ It's preferable to fetch e-mails first to avoid copying large attachments around Avoid unzipping and rezipping the Slack export. Doing so can modify the directory structure of the archive which could cause issues with the import process. -4. Convert Slack import to Mattermost's bulk export format ----------------------------------------------------------- +.. _transform-the-export-for-mattermost: + +3. Transform the export for Mattermost +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now that you have a Slack export file with emails and attachments, let's convert this information into Mattermost's bulk import format using the import preparation tool ``mmetl``. @@ -108,18 +193,60 @@ Next, run the command below to create a Mattermost bulk import file. Replace ``< ./mmetl transform slack --team --file export-with-emails-and-attachments.zip --output mattermost_import.jsonl -The tool outputs a `.jsonl `__ file containing all of your users, channels, and posts. It also creates a ``data`` folder that contains all of your attachments. Users' default authentication method will be configured as email/password. See the `section below <#use-the-imported-team>`__ for instructions on migrating the auth method to another choice. +The tool outputs a `.jsonl `__ file containing all of your users, channels, and posts. It also creates a ``data`` folder that contains all of your attachments. It doesn't matter what you name the ``.jsonl`` file. You can name it what you want with the `--output` flag as shown above. It just needs to be a ``.jsonl`` file. -.. important:: +Debug transform +^^^^^^^^^^^^^^^ + +The ``mmetl transform`` process produces a ``transform-slack.log`` file that records INFO level output by default. + +If you run the import commands with the ``--debug`` flag, the log will include additional ``DEBUG`` level entries. These entries provide more granular detail on each phase of the process, which can help identify where the transformation may be slowing down or failing. + +MMETL parsing phases +^^^^^^^^^^^^^^^^^^^^ + +When parsing a Slack export file with the ``mmetl`` tool, the process runs through four phases. You can track progress by monitoring the log output during each phase. Understanding these phases helps set expectations for how long the parsing step may take. + +**1. Reading the import file** + +In this phase, ``mmetl`` reads through the Slack export file. Example log line: + +``{"file":"parse.go:359","level":"info","msg":"Processing file 1 of 10335: aluminum-white-lightbulb/","time":"2024-03-11T20:41:09-04:00"}`` + +This step usually takes 5–10 minutes depending on the size of the export archive. + +**2. Converting user mentions** + +During this phase, ``mmetl`` converts Slack user mentions into Mattermost-compatible format. Example log line: + +``{"file":"parse.go:224","level":"debug","msg":"Slack Import: converting user mentions for channel touchscreen-headphones-sleek. 1 of 400","time":"2024-03-11T20:41:10-04:00"}`` + +This step can be time-consuming on large imports and may take several hours. + +**3. Converting channel mentions** + +In this phase, channel references are updated. Example log line: - It doesn't matter what you name the ``.jsonl`` file. You can name it what you want with the `--output` flag as shown above. It just needs to be a ``.jsonl`` file. +``{"file":"parse.go:259","level":"debug","msg":"Slack Import: converting channel mentions for channel robust-smart-home-device-matrix. 95 of 400","time":"2024-03-11T20:41:48-04:00"}`` -5. Import data into Mattermost ------------------------------- +This step typically completes in about half the time required for user mentions. + +**4. Converting post markup** + +Finally, Slack message formatting is converted into Mattermost-compatible Markdown. Example log line: + +``{"file":"parse.go:330","level":"debug","msg":"Slack Import: converting markdown for channel vertex-robust-vacuum. 120 of 400","time":"2024-03-11T20:41:58-04:00"}`` + +This is the fastest step and usually completes quickly. + +.. _import-data-into-mattermost: + +4. Import data into Mattermost +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can upload the export through Mattermost's API from the server or from another computer using mmctl commands. The server will save the import in its file store before running the import (e.g. AWS S3), so there will be time spent uploading/downloading the file in this case. -The migration is idempotent, meaning that you can run multiple imports that contain the same posts, and there won't be duplicated created posts in Mattermost. Each post is imported with the correct user/author and ``created_at`` value from your Slack instance. Threads are kept intact with the import. +The migration is idempotent, meaning that you can run multiple imports that contain the same posts, and there won't be duplicated created posts in Mattermost. Each post is imported with the correct user/author and ``created_at`` value from your Slack instance. Ensure you have the Mattermost command line tool ``mmctl`` installed. This allows you to perform different tasks that communicate to Mattermost's API. You'll also want to :ref:`configure authentication ` for the tool. @@ -129,11 +256,15 @@ To prepare our files to be uploaded to the server, we need to put both the ``.js zip -r mattermost-bulk-import.zip data mattermost_import.jsonl -Then we can upload the zip file to our Mattermost server: +Then we can upload the zip file to our Mattermost server. These files can be very large, so getting them onto the server can be challenging. You have two primary options for this step: -.. code-block:: sh +- You can use the ``mmctl`` tool: + + .. code-block:: sh - mmctl import upload ./mattermost-bulk-import.zip + mmctl import upload ./mattermost-bulk-import.zip + +- Alternatively, you can move the file directly to the data directory under ``data/import`` and give it a unique name. Run this command to list the available imports: @@ -158,8 +289,44 @@ Debug imports You can use the ``mmctl import job show`` command to view any relevant errors that may have occurred. -.. important:: - Note that if you are part of the user group being imported from Slack, your Mattermost profile must have a matching username and email to the corresponding ``user`` line of the ``jsonl`` file. You can manually edit the file to ensure it matches your Mattermost user. +Fixing unread channels and threads +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After importing, all messages may appear as unread for users. To resolve this issue, run the following SQL queries directly against the Mattermost database: + +.. code-block:: sql + + begin; + UPDATE channelmembers + SET + msgcount = channels.totalmsgcount, + lastupdateat = channels.lastpostat, + lastviewedat = channels.lastpostat, + msgcountroot = channels.totalmsgcountroot + FROM channels + WHERE channelmembers.channelid = channels.id; + + INSERT INTO preferences (UserId, Category, Name, Value) + SELECT + cm.userid, + 'channel_approximate_view_time', + cm.channelid, + cm.lastupdateat + FROM + channelmembers cm + ON CONFLICT (userid, category, name) + DO UPDATE SET + Value = EXCLUDED.Value; + + update preferences + set value = false + where category = 'direct_channel_show'; + + update preferences + set value = false + where category = 'group_channel_show'; + + commit; Additional tools ^^^^^^^^^^^^^^^^ @@ -168,10 +335,10 @@ Additional tools * `mm-importjs `__ - Breaks up large import files into smaller ones, as well as automatically remove null characters in post content when importing data to Mattermost. * `slack-migrate-pinned-posts `__ - Migrates pinned posts from Slack to Mattermost. -Use the imported team -^^^^^^^^^^^^^^^^^^^^^ +Address placeholder emails +^^^^^^^^^^^^^^^^^^^^^^^^^^ -* 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. We recommend administrators search the final import ``jsonl`` file for ``user`` lines for with ``@example.com`` in the email property to address and resolve the missing information prior to import. +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. We recommend administrators search the final import ``jsonl`` file for ``user`` lines with ``@example.com`` in the email property to address and resolve the missing information prior to import. Email verification behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -193,12 +360,112 @@ The email verification process during Slack import depends on who performs the i Account activation ~~~~~~~~~~~~~~~~~~ -* Slack users 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. +* Slack users 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. See the instructions on how to :ref:`migrate user authenticatation to LDAP or SAML `. - * For imports performed by system administrators: Users can immediately use the **Password Reset** feature (no email verification is required). + * For imports performed by System Admins: Users can immediately use the **Password Reset** feature (no email verification is required). * For imports performed by non-administrators: Users must first verify their email addresses, then use the **Password Reset** feature. * Once logged in, Mattermost users will have access to previous Slack messages in the public channels imported from Slack. -* Instructions on how to migrate user authenticatation to LDAP or SAML can be found :ref:`here `. -`Book a live demo `_ or `talk to a Mattermost expert `_ to explore tailored solutions for your organization's secure collaboration needs. Or try Mattermost yourself with a `1-hour preview `_ for instant access to a live sandbox environment. +FAQ +--- + +What additional conderations are there for Slack Enterprise Grid? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Slack Enterprise Grid combines multiple workspaces under a single management plane and the associate export reflect that complexity. An Enterprise Grid export is a single archive containing all workspaces and shared channels. + +Mattermost does not support shared channels between teams, so Slack Shared Channels must be mapped to a single team in Mattermost. We can create this mapping by determining the originating teams in Slack and creating a ``team.json`` mapping file for use with ``mmetl``. Because of the manual effort required to identify and map team IDs, Enterprise Grid migrations are typically more time-consuming than single-workspace migrations. Plan additional time and resources to complete this step successfully. + +Export structure +^^^^^^^^^^^^^^^^ + +At the root level, you’ll see shared channels that span across Slack workspaces, and under ``/teams/`` you’ll find per-workspace data such as channels and users files. A typical structure looks like: + +.. code-block:: text + + Enterprise Grid Export/ + ├── channel1/ + │ ├── 2023-01-01.json + │ └── 2023-01-02.json + ├── channel2/ + │ ├── 2023-05-01.json + │ └── 2023-05-02.json + ├── teams/ + │ ├── team1/ + │ │ ├── channel3/ + │ │ │ ├── 2023-05-01.json + │ │ │ └── 2023-05-02.json + │ │ ├── channels.json + │ │ ├── mpims.json + │ │ ├── dms.json + │ │ ├── users.json + │ │ └── groups.json + │ └── team2/ + │ ├── channel4/ + │ │ ├── 2023-05-01.json + │ │ └── 2023-05-02.json + │ ├── channels.json + │ ├── mpims.json + │ ├── dms.json + │ ├── users.json + │ └── groups.json + ├── channels.json + ├── org_users.json + ├── mpims.json + ├── dms.json + └── groups.json + +Mapping shared channels to Mattermost teams +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Download the full Enterprise Grid export from Slack. + +2. To determine where each shared channel belongs in Mattermost, looks for a ``team`` attribute on the first post in each shared channel. These ``team`` values map the channel back to its originating workspace in Slack. This is where each shared channel will live in Mattermost once imported. + + .. code-block:: json + + { + "client_msg_id": "", + "type": "", + "text": "", + "user": "U1", + "ts": "1695219722.430309", + "blocks": [ ], + "team": "team1", + "user_team": "team1", + "source_team": "team1", + "user_profile": { } + }, + +3. Create a ``teams.json`` file that maps Slack team IDs to each ``team`` attribute you found above. For example: + + .. code-block:: json + + { + "T0001" : "team1", + "T0002" : "team2" + } + +4. Run the ``mmetl grid-transform`` command to split the Enterprise Grid export into per-team files: + + .. code-block:: bash + + ./mmetl grid-transform -f slackexport.zip -t teams.json + +This process outputs a new archive for each team defined in ``teams.json``. Once split, you can continue the standard Mattermost import process on each file. + +Are there features of Slack that are not supported for migration to Mattermost? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Slack import process focuses on preserving core collaboration data such as messages, files, channels, and users. However, certain Slack features are not supported by the Mattermost product and thus will not be migrated using the import tools in this document: + +- **Slack apps and integrations**: Installed apps, bots, slash commands, webhooks, workflow builder and other integrations do not migrate. Most integrations supported by Slack can be recreated using the :doc:`integration and automation ` options in Mattermost. +- **Stared conversations**: Starred conversations are not preserved. +- **User groups**: User groups from Slack are not preserved, however they can be recreated in Mattermost using the :doc:`Custom Groups ` feature. +- **Threaded Converations**: Slack threads are mostly supported, however some threading relationships may not always be preserved given the differences in how Mattermost and Slack threading works. +- **Canvases**: Canvases are not supported in Mattermost and will not be migrated. +- **User presence and profiles**: User status (online/away), profile pictures, and custom profile fields do not carry over. Users will need to update their profiles in Mattermost. +- **Channel memberships for deactivated users**: Deactivated or deleted Slack users are not migrated to Mattermost. + +Because of these limitations, some manual reconfiguration is typically required after the import, especially for workflows and integrations. Support from a `Mattermost expert is available `_ for your Slack migration. \ No newline at end of file diff --git a/source/administration-guide/onboard/migrating-from-hipchat-to-mattermost.rst b/source/administration-guide/onboard/migrating-from-hipchat-to-mattermost.rst deleted file mode 100644 index 692e38e6f46..00000000000 --- a/source/administration-guide/onboard/migrating-from-hipchat-to-mattermost.rst +++ /dev/null @@ -1,72 +0,0 @@ -:orphan: - -.. Users trying to access this page are now redirected to /administration-guide/onboard/migrating-to-mattermost.html#migrating-from-slack instead - -Migrate from HipChat to Mattermost -================================== - -You can migrate HipChat users and message histories to Mattermost using the following guidelines. - -Step 1: Set up your Mattermost instance ------------------------------------------ - -- `Go to Mattermost download page `__ to install Mattermost in your environment using one of the installation guides for Linux binary install, Docker install or various orchestrated installations. - -Questions? Please visit our `troubleshooting forum `__ for help. - -Step 2: Export your data from HipChat Server or HipChat Data Center ---------------------------------------------------------------------- - -HipChat Server/HipChat Data Center -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you’re able to upgrade HipChat Server or HipChat Data Center to the latest version, we recommend using Group Export Dashboard to export your data. If you’re unable to upgrade, see Command Line Interface procedure below. - -*Using the Group Export Dashboard* - -#. Log in to your Hipchat Server (e.g. hipchat.yourcompany.com). -#. Click on **Server Admin > Export**. -#. Select the data to export. -#. In the **Password** and **Confirm Password** fields, create a password to protect your archive files (Store this password as it is not saved anywhere else). -#. Click **Export**. Once the export is done, you will receive an email with a link to download the file. - -*If you’re unable to use the Group Export Dashboard, use the command line interface to export* - -#. Go to **CLI**. -#. Enter ``hipchat export --export -p your_password``. -#. Once the export is done, you will receive an email with a link to download the file. - -Step 3: Import your data into Mattermost ----------------------------------------- - -1. Follow the :doc:`Mattermost Bulk Load Tool ` guide to import your data into Mattermost. Files exported from HipChat will need to be converted to the format required by Mattermost. Talk to a `Mattermost Expert `_ if you require assistance in the conversion. - -2. You are also encouraged to use the HipChat import tool created by Herzum: https://github.com/herzum/HC2MM. - -If you’re interested in contributing or testing any community contributed solution, please let us know at info@mattermost.com, Twitter or Mattermost forums at https://forum.mattermost.com. - -3. Alternatively, talk to a `Mattermost Expert `_ for partner recommendations for your region to assist in your import. - -Step 4: Onboard your users into Mattermost -------------------------------------------- - -After importing users, you can send out an announcement via email or via your old system (or both) to let users know how to log into Mattermost with their old accounts or how to create new accounts. - -**Announcing Mattermost onboarding in your previous messaging system:** - -Use the following message template to alert users of the migration:: - - @all, we’re moving communications to a new Mattermost server. You can start your new account by going to the [your new location, e.g. ``https://yourcompany.com/mattermost``], selecting **I forgot my password**, and entering the email you used on this system in the Reset Password page to set up new credentials. Your message history and channels should carry over from this system into Mattermost. Any questions? Please let us know. - -**Announcing Mattermost onboarding using email using username/password:** - -#. Get a list of email addresses of people in the new system by running a database query on Mattermost. Run ``SELECT Email FROM Users`` from either PostgreSQL or MySQL databases. -#. Adapt the :doc:`migration announcement email template ` to let users know how to reclaim their old accounts or start new ones. - -Onboard users using SSO in Mattermost -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Alternatively, you can choose to set up SSO (Single Sign-on) with Mattermost if you are using an Enterprise version. - -#. Configure :doc:`Active Directory/LDAP ` or :doc:`SAML Single Sign-on ` from the **System Console**. -#. Adjust the messaging templates above to remove "password reset" references and indicate which SSO system credentials Mattermost has configured. diff --git a/source/administration-guide/onboard/migrating-to-mattermost.rst b/source/administration-guide/onboard/migrating-to-mattermost.rst index a018923808a..40c6e71a460 100644 --- a/source/administration-guide/onboard/migrating-to-mattermost.rst +++ b/source/administration-guide/onboard/migrating-to-mattermost.rst @@ -4,33 +4,61 @@ Migration guide .. include:: ../../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -Thousands of organizations are moving to Mattermost for powerful, flexible, and easy-to-manage workplace collaboration. Mattermost deploys as a single Linux binary with PostgreSQL, and can scale from dozens to tens of thousands of users in a single channel. +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. -This guide summarizes different approaches to migrating to Mattermost from other tools, including :doc:`Slack `, :doc:`HipChat `, `Jabber <#migrate-from-jabber>`_, `Pidgin <#migrate-from-pidgin>`_, `Bitnami <#migrate-from-bitnami>`_, and other `bespoke messaging solutions <#migrate-from-bespoke-messaging-solutions>`_, as well as `migrating Mattermost server <#migrate-mattermost-server>`_ to another server instance. +`Book a live demo `_ or `talk to a Mattermost expert `_ to explore tailored solutions for your organization's secure collaboration needs. Or try Mattermost yourself with a `1-hour preview `_ for instant access to a live sandbox environment. -Migrate from Slack ------------------- +Move Mattermost to a new server +--------------------------------- -See the :doc:`Migrate from Slack ` documentation for details on migrating from Slack 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. -Migrate from HipChat --------------------- +1. Back up your SOURCE Mattermost server. See :doc:`Backup and Disaster Recovery documentation `. +2. Upgrade your SOURCE Mattermost server to the latest major build version. See :doc:`Upgrading Mattermost Server documentation `. +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. -See the :doc:`Migrate from HipChat ` documentation for details on migrating from HipChat Server and HipChat Data Center to Mattermost. +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 :ref:`upgrade the Team Edition of Mattermost to Enterprise Edition using the upgrade guide `. + +Move a GitLab Omnibus instance of Mattermost +-------------------------------------------- + +From Mattermost v11, Mattermost Omnibus has reached end of life. Current Omnibus deployments will continue working as they do today until you decide to migrate. However, after v10.12, you won’t receive security updates or new features through Omnibus. We recommend migrating to one of our :ref:`supported deployment methods `, which will ensure you continue receiving security patches and feature updates. -Migrate from Jabber +See the `Mattermost Omnibus migration guidance `_ for detailed instructions on migrating your GitLab Omnibus instance of Mattermost. + +See the Mattermost Support Knowledge Base article on `Migrating Mattermost DB from GitLab Omnibus PostgreSQL installation to a standalone PostgreSQL `_. This migration is commonly needed when separating Mattermost from GitLab or when moving to dedicated database infrastructure. + +Move from Slack +------------------ + +See the :doc:`Migrate from Slack ` documentation for details on migrating from Slack 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. Read more about their `case study `__ online. -Migrate from Pidgin +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 `__, 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 PC. -Migrate from Bitnami +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. @@ -39,7 +67,7 @@ You can modify the script by adding the ``--lower-case-table-names=1`` switch to 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. -Migrate from bespoke messaging solutions +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. @@ -51,40 +79,9 @@ If your data in the bespoke messenger is vital, consider: 1. :doc:`Mattermost bulk load tool `: Use the Mattermost bulk load tool to ETL from your bespoke system to Mattermost. 2. `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. 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 HipChat, Flowdock, Campfire, Chatwork, Hall, or CSV files to Slack `_ and then export to a Slack export file and import the file into Mattermost. +4. **Export to Slack, then import to Mattermost:** `Export 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: 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. - -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 `_. - - ----- - -Migrate Mattermost from one server to another ---------------------------------------------- - -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 :doc:`Backup and Disaster Recovery documentation `. -2. Upgrade your SOURCE Mattermost server to the latest major build version. See :doc:`Upgrading Mattermost Server documentation `. -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 :ref:`upgrade the Team Edition of Mattermost to Enterprise Edition using the upgrade guide `. - -`Book a live demo `_ or `talk to a Mattermost expert `_ to explore tailored solutions for your organization's secure collaboration needs. Or try Mattermost yourself with a `1-hour preview `_ for instant access to a live sandbox environment. +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. \ No newline at end of file diff --git a/source/deployment-guide/server/prepare-mattermost-mysql-database.rst b/source/deployment-guide/server/prepare-mattermost-mysql-database.rst index 82e8ba939a9..3ea248281c3 100644 --- a/source/deployment-guide/server/prepare-mattermost-mysql-database.rst +++ b/source/deployment-guide/server/prepare-mattermost-mysql-database.rst @@ -254,7 +254,7 @@ You can perform searches without this configuration by adding wildcards ``*`` to Migrate from Bitnami to a self-hosted Mattermost deployment ------------------------------------------------------------ -If you're planning a migration from Bitnami to a self-hosted Mattermost installation with a MySQL database, read these notes in our migration guide: :ref:`Migrating from Bitnami `. +If you're planning a migration from Bitnami to a self-hosted Mattermost installation with a MySQL database, read these notes in our migration guide: :ref:`Migrating from Bitnami `. Downgrade Mattermost v6.0 to v5.38 ----------------------------------- diff --git a/source/product-overview/certifications-and-compliance.rst b/source/product-overview/certifications-and-compliance.rst index 34ddd141227..d8c529b7908 100644 --- a/source/product-overview/certifications-and-compliance.rst +++ b/source/product-overview/certifications-and-compliance.rst @@ -61,7 +61,7 @@ Data management Data portability ^^^^^^^^^^^^^^^^^ -- **Data Import:** Use the :doc:`bulk loading tool ` to migrate data from an existing messaging system, or for pre-populating a new installation with data. :ref:`Review this guide ` which summarizes the different approaches and meets the `Right to Data Portability `_ principle. +- **Data Import:** Use the :doc:`bulk loading tool ` to migrate data from an existing messaging system, or for pre-populating a new installation with data. :doc:`Review our migrate from Slack guidance ` which summarizes the different approaches and meets the `Right to Data Portability `_ principle. - **Data Export:** Use :doc:`compliance exports ` to export conversations from public, private and direct message channels in XML or EML format. Those in Team Edition can export conversations directly from the database, both in PostgreSQL and in MySQL. Accessibility compliance diff --git a/source/product-overview/deprecated-features.rst b/source/product-overview/deprecated-features.rst index 333b266afea..01ad12faf68 100644 --- a/source/product-overview/deprecated-features.rst +++ b/source/product-overview/deprecated-features.rst @@ -22,7 +22,7 @@ Mattermost Server v11.0.0 (October 2025) - The ``ExperimentalStrictCSRFEnforcement`` setting will be renamed to ``StrictCSRFEnforcement`` and the default value will be changed to ``true`` for new installations. See more details in `this forum post `__. - The ``registerPostDropdownMenuComponent`` hook in the web app’s plugin API will be removed in favour of ``registerPostDropdownMenuAction``. See more details in `this forum post `__. - The web app will no longer expose the `Styled Components `__ dependency for use by web app plugins. See more details in `this forum post `__. -- Omnibus support will be deprecated. The last ``mattermost-omnibus`` release will be v10.12. See more details in `this forum post `__. +- Omnibus support will be deprecated. The last ``mattermost-omnibus`` release will be v10.12. See more details in `this forum post `__. Learn how to :ref:`move a GitLab Omnibus instance of Mattermost `. - Deprecated ``include_removed_members`` option in ``api/v4/ldap/sync`` will be removed. Admins can use the LDAP setting ``ReAddRemovedMembers``. - All telemetry support will be removed from Mattermost. The system will no longer collect or send telemetry data to external services. Customers that have the NPS plugin enabled can remove it as it will no longer sent the feedback over through telemetry. - Format query parameter requirement in ``/api/v4/config/client`` endpoint will be deprecated. diff --git a/source/redirects.py b/source/redirects.py index c564d626a5d..98662d74ce3 100644 --- a/source/redirects.py +++ b/source/redirects.py @@ -371,7 +371,7 @@ "administration/health-check.html": "https://docs.mattermost.com/administration-guide/manage/health-checks.html", "administration/hipchat-migration-guidelines.html": - "https://docs.mattermost.com/administration-guide/onboard/migrating-from-hipchat-to-mattermost.html", + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html", "administration/image-proxy.html": "https://docs.mattermost.com/deployment-guide/server/image-proxy.html", "administration/important-upgrade-notes.html": @@ -555,6 +555,18 @@ "https://docs.mattermost.com/administration-guide/configure/environment-configuration-settings.html#enable-secure-file-preview-on-mobile", "administration-guide/configure/site-configuration-settings.html#allow-pdf-link-navigation-on-mobile": "https://docs.mattermost.com/administration-guide/configure/environment-configuration-settings.html#allow-pdf-link-navigation-on-mobile", +"administration-guide/onboard/migrating-to-mattermost.html#migrate-from-slack": + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html#move-from-slack", +"administration-guide/onboard/migrating-to-mattermost.html#migrate-from-jabber": + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html#move-from-jabber", +"administration-guide/onboard/migrating-to-mattermost.html#migrate-from-pidgin": + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html#move-from-pidgin", +"administration-guide/onboard/migrating-to-mattermost.html#migrate-from-bitnami": + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html#move-from-bitnami", +"administration-guide/onboard/migrating-to-mattermost.html#migrate-from-bespoke-messaging-solutions": + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html#move-from-bespoke-messaging-solutions", +"administration-guide/onboard/migrating-to-mattermost.html#migrate-mattermost-from-one-server-to-another": + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html#move-mattermost-to-a-new-server", # Channels redirects "channels/find-channels.html": @@ -3651,7 +3663,7 @@ "onboard/user-provisioning-workflows.html": "https://docs.mattermost.com/administration-guide/onboard/user-provisioning-workflows.html", "onboard/migrating-from-hipchat-to-mattermost.html": - "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html#migrating-from-slack", + "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html", "onboard/ad-ldap-groups-synchronization.html#enabling-ad-ldap-group-synchronization": "https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html", "onboard/ad-ldap-groups-synchronization.html#enable-ad-ldap-group-synchronization": @@ -3723,6 +3735,7 @@ "onboard/shared-channels.html#frequently-asked-questions": "https://docs.mattermost.com/administration-guide/onboard/connected-workspaces.html#frequently-asked-questions", + # Overview redirects "overview/architecture.html": "https://docs.mattermost.com/deployment-guide/application-architecture.html",