diff --git a/source/conf.py b/source/conf.py index c09815b3ca6..d4cc8237d08 100644 --- a/source/conf.py +++ b/source/conf.py @@ -2850,7 +2850,7 @@ def setup(_: Sphinx): "onboard/ad-ldap.html#active-directory-ldap-setup-e10-e20": "https://docs.mattermost.com/onboard/ad-ldap.html#active-directory-ldap-setup", "onboard/migrating-from-hipchat-to-mattermost.html": - "https://docs.mattermost.com/onboard/migrating-to-mattermost.html#migrating-from-slack", + "https://docs.mattermost.com/onboard/migrating-to-mattermost.html", "onboard/ad-ldap-groups-synchronization.html#enabling-ad-ldap-group-synchronization": "https://docs.mattermost.com/onboard/ad-ldap-groups-synchronization.html#enable-ad-ldap-group-synchronization", "onboard/ad-ldap-groups-synchronization.html#using-ad-ldap-group-synchronization": diff --git a/source/guides/self-hosted-administration.rst b/source/guides/self-hosted-administration.rst index bdd4868fa70..329199d211a 100644 --- a/source/guides/self-hosted-administration.rst +++ b/source/guides/self-hosted-administration.rst @@ -17,6 +17,7 @@ This section of the guide is for system admins of self-hosted Mattermost servers Configure CloudFront to host static assets Use an outbound proxy Migration guide + Migrate from Slack Migration from MySQL to PostgreSQL Chinese, Japanese, and Korean search Customize Mattermost @@ -35,6 +36,7 @@ This section of the guide is for system admins of self-hosted Mattermost servers * :doc:`Configure CloudFront to host Mattermost static assets ` - Improve caching performance to reduce content load times. * :doc:`Use an outbound proxy ` - Monitor outbound traffic and control the websites that can appear in embedded content. * :doc:`Migration guide ` - Learn how to migrate from other chat services to Mattermost. +* :doc:`Migrate from Slack ` - Learn how to migrate from Slack to Mattermost. * :doc:`Migration guidelines from MySQL to PostgreSQL ` - Learn how to migrate the Mattermost database from MySQL to PostgreSQL. * :doc:`Chinese, Japanese, and Korean search ` - Set up search capabilities for teams communicating via Chinese, Japanese, or Korean. * :doc:`Whitelabel Mattermost ` - Whitelabel the Mattermost server and apps. diff --git a/source/onboard/migrate-from-slack.rst b/source/onboard/migrate-from-slack.rst new file mode 100644 index 00000000000..722f65a4bab --- /dev/null +++ b/source/onboard/migrate-from-slack.rst @@ -0,0 +1,187 @@ +Migrate from Slack +================== + +.. include:: ../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + +Migrating from Slack to Mattermost involves the following steps: + +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>`__ + +1. Prepare your Mattermost server +--------------------------------- + +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 `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. + +Make sure you are running on a supported version of `Mattermost `__ to benefit from the most up-to-date functionality and fixes. + +2. Generate a Slack import +-------------------------- + +Slack offers two ways to `export your data from their product `_. + +1. Regular export - Contains only public channel posts. This does not include private channels, DMs, or group conversations. This can be generated from **Slack > Administration > Workspace settings > Import/Export Data > Export > Start Export**. +2. Corporate export - Contains all posts. This includes public channels, private channels, DMs and group messages. You must `request this export type from Slack directly `__. + +You will receive a zip file containing the following contents: + +- Channels (``channels.json``) +- Users (``users.json``) +- Direct messages (``dms.json``) (Corporate export) +- Private channels (``groups.json``) (Corporate export) +- Group direct messages (``mpims.json``) (Corporate export) +- App activity logs (``integration_logs.json``) +- Folders containing posts for every public channel +- Folders containing posts for every private channel (Corporate exports) + +.. 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 `__. + +3. Download file attachments and email addresses +------------------------------------------------ + +When you download your Slack export zip file, some data will be missing from the zip file: + +- User emails +- Uploaded attachment contents + +We need to create a Slack app in order to gather these contents. Follow these steps to create a Slack app: + +1. Go to https://api.slack.com/apps. +2. Select **Create New App**. +3. Select **From scratch**. +4. Name the app **Slack Advanced Exporter** and select the workspace. You'll have to do this for every workspace. Then select **Create App**. +5. Select **OAuth & Permissions** on the left-hand side of the screen. Then scroll down to **Scopes**. +6. Under **Bot Token Scopes** type in and select the following scopes: + - ``users:read`` + - ``users:read.email`` + +7. Scroll up and select **Install to Workspace**. +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. + +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:: bash + + ./slack-advanced-exporter --input-archive --output-archive export-with-emails.zip fetch-emails --api-token + ./slack-advanced-exporter --input-archive export-with-emails.zip --output-archive export-with-emails-and-attachments.zip fetch-attachments --api-token + +.. note:: + + - The first command collects all of the user emails and creates the file ``export-with-emails.zip``. The second command fetches attachments and creates the file ``export-with-emails-and-attachments.zip``, which we will use going forward. + - The second command can take a long time if you have a large number of file uploads. If it's interrupted, delete the file generated (if any), and start again. + +The file ``export-with-emails-and-attachments.zip`` now contains all the information necessary to be imported into Mattermost. + +It's preferable to fetch e-mails first to avoid copying large attachments around. Make sure you choose different file names at each stage, as the tool does not support in-place modifications. + +.. important:: + + 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 +---------------------------------------------------------- + +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``. Download the latest release of ``mmetl`` for your `OS and architecture `__. Run ``mmetl help`` to learn more about using the tool. + +Next, run the following command to create a Mattermost bulk import file. Replace ```` with the name of your team in Mattermost. Note that the name needs to be one word like "my-team". + +.. code:: bash + + ./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. + +.. important:: + + 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. + +5. Import data into Mattermost +------------------------------ + +We have two options to run the import process: + +1. Uploading the export through Mattermost's API, via command line ``mmctl`` from the server or from another computer. This option is required for Mattermost Cloud deployments. +2. SSH into the Mattermost server's host, upload the export file to this server's file system somehow, and use the ``mattermost`` command to process the export file. + +For the first option, the server will save the import in its file store before running the import (e.g. AWS S3 if you are using that as your file store), so there will be time spent uploading/downloading the file in this case. Depending on system/environment specs, a 5GB import should be fine over ``mmctl`` import. Imports greater than 10GB should use the ``mattermost`` binary for import. + +The migration is idempotent, meaning that you can run multiple imports that contain the same posts, and there will not 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 in tact with the import. + +Option 1: Upload export via ``mmctl`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 `configure authentication `__ for the tool. + +To prepare our files to be uploaded to the server, we need to put both the ``.jsonl`` file and ``data`` folder together into a zip file. + +.. code:: bash + + zip -r mattermost-bulk-import.zip data mattermost_import.jsonl + +Then we can upload the zip file to our Mattermost server: + +.. code:: bash + + mmctl import upload ./mattermost-bulk-import.zip + +Run this command to list the available imports: + +.. code:: bash + + mmctl import list available + +Run this command to process the import. Replace ```` with the name you got from the ``mmctl import list available`` command: + +.. code:: bash + + mmctl import process + +Finally, run this command to view the status of the import process job. If the job status shows as ``pending``, then wait before running the command again. The ``--json`` flag is required to view the possible error message. Replace ```` with the id you got from the ``mmctl import list process`` command: + +.. code:: bash + + mmctl import job show --json + +Option 2: Use the ``mattermost`` command to run the export +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First get the ``.jsonl`` file and ``data`` folder onto your server using something like ``scp``. Then you'll use the ``mattermost`` binary to process the bulk import data: + +.. code:: bash + + mattermost import bulk ./mattermost_import.jsonl --import-path ./data --apply + +Debug imports +^^^^^^^^^^^^^ + +If you choose the ``mmctl`` option above, you can use the ``mmctl import job show`` command to view any relevant errors that may have occurred. If you run into problems which the error message does not help to resolve, please try the second option of using the ``mattermost bulk import`` command. The ``mmctl`` import process does not give you any additional debugging information, even in the Mattermost server logs. + +.. 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. + +Additional tools +^^^^^^^^^^^^^^^^ + +* `mm-emoji `__ - Designed to smoothly transition emojis from a Slack instance to Mattermost. +* `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 +^^^^^^^^^^^^^^^^^^^^^ + +* 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. +* 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. +* Instructions on how to migrate user authenticatation to LDAP or SAML can be found `here `__. diff --git a/source/onboard/migrating-from-hipchat-to-mattermost.rst b/source/onboard/migrating-from-hipchat-to-mattermost.rst index 72e05e35b80..cb469edf014 100644 --- a/source/onboard/migrating-from-hipchat-to-mattermost.rst +++ b/source/onboard/migrating-from-hipchat-to-mattermost.rst @@ -2,8 +2,8 @@ .. Users trying to access this page are now redirected to /onboard/migrating-to-mattermost.html#migrating-from-slack instead -Migrating from HipChat to Mattermost -===================================== +Migrate from HipChat to Mattermost +================================== You can migrate HipChat users and message histories to Mattermost using the following guidelines. diff --git a/source/onboard/migrating-to-mattermost.rst b/source/onboard/migrating-to-mattermost.rst index a302c8ba87f..d04b78eece9 100644 --- a/source/onboard/migrating-to-mattermost.rst +++ b/source/onboard/migrating-to-mattermost.rst @@ -6,78 +6,47 @@ Migration guide 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. -This guide summarizes different approaches to migrating from one Mattermost deployment to another, and migrating from other tools (such as Slack, HipChat, Jabber, and bespoke solutions) to Mattermost. +This guide summarizes different approaches to migrating to Mattermost from other tools, including `Slack `__, `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. .. contents:: On this page :backlinks: top - :depth: 1 - :local: + :depth: 2 -Migrate Mattermost 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 `__. -2. Upgrade your SOURCE Mattermost server to the latest major build version. See `Upgrading Mattermost Server documentation `__. -3. Install the latest major build of Mattermost server as your DESTINATION. See `Install Mattermost documentation `__ for details. - - - 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. +Migrate from Slack +------------------ -Once your migration is complete and verified, you can optionally `upgrade the Team Edition of Mattermost to Enterprise Edition using the upgrade guide `__. +See the `Migrate from Slack `__ documentation for details on migrating from Slack to Mattermost. -Migrate to Mattermost from bespoke messaging solutions -------------------------------------------------------- +Migrate from HipChat +-------------------- -Many enterprises run bespoke, unsupported, lightly documented messaging systems driven by the initial excitement of the product's promise. +See the `Migrate from HipChat `__ documentation for details on migrating from HipChat Server and HipChat Data Center to Mattermost. -Often the solutions were championed by tech-savvy early adopters who loved a few features and pushed out the solution broadly. +Migrate from Jabber +------------------- -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. +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. -Why IT teams choose to leave bespoke solutions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Migrate from Pidgin +------------------- -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: +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. -1. Is the solution backed by a commercial entity with significant legal obligations to ensure the safety and security of the product? -2. Is there a security bulletin available to alert our organization of high-priority security updates, with clear instructions to apply the updates? -3. Does the solution have a clear and up-to-date list of security updates? -4. 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? -5. 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. +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. -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 `__. +Migrate from Bitnami +-------------------- -Why IT teams choose Mattermost over bespoke solutions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. -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. +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. -In addition, IT teams prefer Mattermost for its specific `security assurances `__: +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. -1. 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. -2. 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. -3. Mattermost maintains an `up-to-date list of security updates `__ for both its open source and commercial offerings. -4. To keep IT teams safe, Mattermost waits 14 days after releasing a security patch before disclosing the specific details of the vulnerability each addresses. -5. 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. +Migrate from bespoke messaging solutions +----------------------------------------- -Bring data from bespoke solutions into Mattermost -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. @@ -97,165 +66,59 @@ Sometimes systems running in parallel turn into a hard switch migration when a b 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. -Migrate from Slack ------------------- - -Slack offers two ways to `export your data from their product `_. - -1. 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. -2. You can request a "Corporate Export" from Slack directly to get a larger export including private channels, direct, and group messages. - -.. note:: - - 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 `__. - -Use the Mattermost mmetl tool and bulk import -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This method is the recommended way to import Slack's corporate export file, but will work with any Slack export file. - -1. Prepare your Mattermost server -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -We recommend you create a new team in Mattermost to hold the imported Slack data. You can import this into an existing team, but ensure there are no channel name collisions. Also, make sure that all users in Mattermost have the same username as in Slack, otherwise the import will fail. Also, system administrator roles will be overwritten if the usernames match and the user isn't an admin on the Slack workspace. - -2. Generate a Slack import -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The first step is to generate a `Slack export `_. - -.. note:: - - Make sure not to unzip and rezip the Slack export. Doing that can modify the directory structure of the archive which could cause issues with the import process. - -Next, follow these steps to create a bot token: - -1. Go to https://api.slack.com/apps. -2. Select **Create New App**. -3. Select **From scratch**. -4. Name the app something like "Slack Advanced Exporter" and select the workspace. You'll have to do this for every workspace. Then create the app. -5. Select **OAuth & Permissions** and scroll down to **Scopes**. -6. Under **Bot Token Scopes** select ``users:read`` and ``users:read.email``. -7. Scroll up and select **Install to Workspace**. -8. Grant the app permissions. -9. Copy the Bot User OAuth Token and save it somewhere convenient. - -3. Download file attachments and email addresses -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Slack export does not include file attachments and email addresses, so you must use ``slack-advanced-exporter`` to download them. Download the latest release of ``slack-advanced-exporter`` for your OS and architecture `here `__ and extract it. - -Once it's installed, run these commands. Replace ```` with the Slack token you generated earlier and ```` with the `path `__ to your file. - -.. note:: - - - You'll end up with two files (``export-with-emails.zip`` and ``export-with-emails-and-attachments.zip``). The file ``export-with-emails.zip`` will not have attachments. - - The second command can take a long time if you have a large number of file uploads. If it's interrupted, delete the file generated (if any), and start again. - -.. code:: bash - - slack-advanced-exporter --input-archive --output-archive export-with-emails.zip fetch-emails --api-token - slack-advanced-exporter --input-archive export-with-emails.zip --output-archive export-with-emails-and-attachments.zip fetch-attachments - -The file ``export-with-emails-and-attachments.zip`` now contains all the information necessary to be imported into Mattermost. - -4. Convert Slack import to Mattermost bulk export format -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Now that you have a Slack export file with emails and attachments you have to convert it to the Mattermost format using ``mmetl``. Download the latest release of ``mmetl`` for your OS and architecture `here `__ and extract it to your $PATH like with ``slack-advanced-exporter``. The same caveat applies. - -Next, run this command to do the conversion. Replace ```` with the name of your team: - -.. code:: bash - - ./mmetl transform slack --team --file export-with-emails-and-attachments.zip --output mattermost_import.jsonl - -Next you have to create a zip file with the ``mattermost_import.jsonl`` file and the directory ``bulk-export-attachments`` (which needs to be moved to a subdirectory ``data`` first) that contains the attachments. On Linux and macOS you can use this command: - -.. code:: bash - - zip -r mattermost-bulk-import.zip data mattermost_import.jsonl - -The file ``mattermost-bulk-import.zip`` is now ready to import into Mattermost. - -5. Import into Mattermost -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Now you can start the import process. Once you have ``mmctl`` installed and authenticated use this command to upload ``mattermost-bulk-import.zip``: - -.. code:: bash - - mmctl import upload ./mattermost-bulk-import.zip - -Run this command to list the available imports: - -.. code:: bash - - mmctl import list available - -Run this command to process the import. Replace ```` with the name you got from the ``mmctl import list available`` command: - -.. code:: bash - - mmctl import process - -Finally, run this command to view the status of the import process job. If the job status shows as ``pending``, then wait before running the command again. The ``--json`` flag is required to view the possible error message. Replace ```` with the id you got from the ``mmctl import list process`` command: - -.. code:: bash - - mmctl import job show --json - -Debugging imports -^^^^^^^^^^^^^^^^^ - -The ``mmctl import job show`` shows a detailed error message. If you run into problems which the error message does not help to resolve, your best bet is to use the ``mattermost bulk import`` command. The ``mmctl`` import process does not give you any additional debugging information, even in the Mattermost server logs. +Why IT teams choose to leave bespoke solutions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Additional tools -^^^^^^^^^^^^^^^^ +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. -* `mm-emoji `__ - Designed to smoothly transition emojis from a Slack instance to Mattermost. -* `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. +When IT teams are asked to maintain a bespoke messaging solution, they often need to consider security issues such as the following: -Use the Mattermost web app (deprecated) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1. Is the solution backed by a commercial entity with significant legal obligations to ensure the safety and security of the product? +2. Is there a security bulletin available to alert our organization of high-priority security updates, with clear instructions to apply the updates? +3. Does the solution have a clear and up-to-date list of security updates? +4. 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? +5. 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? -.. important:: - The ability to migrate from Slack using the Mattermost web app has been deprecated and removed in favor of using the `Mattermost mmetl tool with bulk import <#use-the-mattermost-mmetl-tool-and-bulk-import>`_. +Bespoke communication products that provide weak security assurance can dramatically increase the risk to IT teams and their organizations. -1. 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. -2. In Mattermost go to **Main Menu > Team Settings > Import > Import from Slack**. Team admin or system admin permission is required to access this menu option. -3. Choose **Select file** to upload the Slack export file and select **Import**. +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. -Use the imported team -^^^^^^^^^^^^^^^^^^^^^^ +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 `__. -* 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. +Why IT teams choose Mattermost over bespoke solutions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Migrate from Bitnami --------------------- +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. -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. +In addition, IT teams prefer Mattermost for its specific `security assurances `__: -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. +1. 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. +2. 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. +3. Mattermost maintains an `up-to-date list of security updates `__ for both its open source and commercial offerings. +4. To keep IT teams safe, Mattermost waits 14 days after releasing a security patch before disclosing the specific details of the vulnerability each addresses. +5. 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. -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 HipChat Server and HipChat Data Center to Mattermost ------------------------------------------------------------------- +Migrate Mattermost server +------------------------- -Please see `HipChat Migration Guide `__. +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 Jabber to Mattermost ---------------------------------- +1. Back up your SOURCE Mattermost server. See `Backup and Disaster Recovery documentation `__. +2. Upgrade your SOURCE Mattermost server to the latest major build version. See `Upgrading Mattermost Server documentation `__. +3. Install the latest major build of Mattermost server as your DESTINATION. -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. + - 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. -Read more about their `case study `__ online. +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. -Migrate from Pidgin to Mattermost ---------------------------------- + - 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. -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. +Once your migration is complete and verified, you can optionally `upgrade the Team Edition of Mattermost to Enterprise Edition using the upgrade guide `__. \ No newline at end of file