Import from Mattermost
You can import your current workspace into a Zulip organization. It’s a great way to preserve your workspace history when you migrate to Zulip, and to make the transition easy for the members of your organization.
The import will include your organization’s:
- Name and Logo
- Message history, including attachments and emoji reactions
- Users, including names, emails, roles, avatars, time zones, and custom profile fields
- Channels, including all user subscriptions
- Custom emoji
Import process overview
Section titled “Import process overview”To import your Mattermost organization into Zulip, you will need to take the following steps, which are described in more detail below:
- Export your Mattermost data.
- Import your Mattermost data into Zulip.
- Get your organization started with Zulip!
Import your organization from Mattermost into Zulip
Section titled “Import your organization from Mattermost into Zulip”Export your Mattermost data
Section titled “Export your Mattermost data”Mattermost’s bulk export tool allows you to export all public and private channel messages.
The instructions below correspond to various common ways Mattermost is installed; if yours isn’t covered, contact us and we’ll help you out.
Replace <username>
and <server_ip>
with the appropriate values below.
- SSH into your Mattermost production server.
ssh <username>@<server_ip>
- Navigate to the directory which contains the Mattermost executable.
On a default install of Mattermost, the directory is
/opt/mattermost/bin
.cd /opt/mattermost/bin - Create an export of all your Mattermost teams, as a tar file.
sudo ./mattermost export bulk export.json --all-teams --attachmentsmkdir -p exported_emojitar --transform 's|^|mattermost/|' -czf export.tar.gz \data/ exported_emoji/ export.json
- Exit your shell on the Mattermost server.
exit
- Finally, copy the exported tar file from the server to your local
computer. You may need to replace
/opt/mattermost/bin/
with the path to your Mattermost installation.scp <username>@<server_ip>:/opt/mattermost/bin/export.tar.gz .
- Make sure you have mmctl installed - these
instructions assume your version is
7.5.1
or higher. - Log into your Mattermost Cloud instance using your administrator credentials.
mmctl auth login https://yourdomain.cloud.mattermost.com
- Create a full export of the server, including attached files.
mmctl export create
- List all of the exports on the server, and copy the name of the
latest one to your clipboard.
mmctl export list
- Download the export to your local computer, replacing
latest_export
with the actual file name from the previous step.mmctl export download latest_export.zip
- SSH into the server hosting your Mattermost docker container.
ssh <username>@<server_ip>
- Navigate to the Mattermost docker directory. On most installs, the
directory should be
mattermost-docker
.cd mattermost-docker/ - Create an export of all your Mattermost teams, as a tar file.
docker exec -it mattermost-docker_app_1 mattermost \export bulk data/export.json --all-teams --attachmentscd volumes/app/mattermost/data/mkdir -p exported_emojitar --transform 's|^|mattermost/|' -czf export.tar.gz \data/ exported_emoji/ export.json
- Exit your shell on the Mattermost server.
exit
- Finally, copy the exported tar file from the server to your local
computer. You may need to replace
mattermost-docker
with the appropriate path for your installation.scp <username>@<server_ip>:mattermost-docker/volumes/app/mattermost/data/export.tar.gz .
- SSH into your GitLab Omnibus server.
- Create an export of all your Mattermost teams, as a tar file.
cd /opt/gitlab/embedded/service/mattermostsudo -u \mattermost /opt/gitlab/embedded/bin/mattermost \--config=/var/opt/gitlab/mattermost/config.json \export bulk export.json --all-teams --attachmentsmkdir -p exported_emojitar --transform 's|^|mattermost/|' -czf export.tar.gz \data/ exported_emoji/ export.json
- Exit your shell on the GitLab Omnibus server.
exit
- Finally, copy the exported tar file from GitLab Omnibus to your local computer.
scp <username>@<server_ip>:/opt/gitlab/embedded/bin/mattermost/export.tar.gz .
Import your data into Zulip
Section titled “Import your data into Zulip”To start using Zulip, you will need to choose between Zulip Cloud and self-hosting Zulip. For a simple managed solution, with no setup or maintenance overhead, you can sign up for Zulip Cloud with just a few clicks. Alternatively, you can self-host your Zulip organization. See here to learn more.
Import into a Zulip Cloud organization
Section titled “Import into a Zulip Cloud organization”If you are using Zulip Cloud, we’ll take it from here! Please email support@zulip.com with the following information:
- The subdomain you would like to use for your organization. Your Zulip chat will
be hosted at
<subdomain>.zulipchat.com
. - The exported data file containing your workspace message history export.
Import into a self-hosted Zulip server
Section titled “Import into a self-hosted Zulip server”Zulip’s import tools are robust, and have been used to import workspaces with 10,000 members and millions of messages. If you’re planning on doing an import much larger than that, or run into performance issues when importing, contact us for help.
- Follow steps 1 and 2 of the guide for installing a new Zulip server.
- Copy the exported data file containing your workspace message
history export onto your Zulip server, and put it in
/tmp/
. - Log in to a shell on your Zulip server as the
zulip
user. - To import into an organization hosted on the root domain
(
EXTERNAL_HOST
) of the Zulip installation, run the following commands, replacing<team-name>
with the name of the Mattermost team you want to import.Alternatively, to import into a custom subdomain, run:cd /tmptar -xf mattermost_data.tar.gzcd /home/zulip/deployments/current./scripts/stop-server./manage.py convert_mattermost_data /tmp/mattermost_data --output /tmp/converted_mattermost_data./manage.py import '' /tmp/converted_mattermost_data/<team-name>./scripts/start-servercd /tmptar -xf mattermost_data.tar.gzcd /home/zulip/deployments/current./scripts/stop-server./manage.py convert_mattermost_data /tmp/mattermost_data --output /tmp/converted_mattermost_data./manage.py import <subdomain> /tmp/converted_mattermost_data/<team-name>./scripts/start-server - Follow step 4 of the guide for installing a new Zulip server.
Import into a self-hosted Zulip server
Section titled “Import into a self-hosted Zulip server”Zulip’s import tools are robust, and have been used to import workspaces with 10,000 members and millions of messages. If you’re planning on doing an import much larger than that, or run into performance issues when importing, contact us for help.
- Follow steps 1 and 2 of the guide for installing a new Zulip server.
- Copy the exported data file containing your workspace message
history export onto your Zulip server, and put it in
/tmp/
. - Log in to a shell on your Zulip server as the
zulip
user. - To import into an organization hosted on the root domain
(
EXTERNAL_HOST
) of the Zulip installation, run the following commands, replacing<team-name>
with the name of the Mattermost team you want to import.Alternatively, to import into a custom subdomain, run:unzip latest_export.zip -d /tmp/my_mattermost_exportmv /tmp/my_mattermost_export/import.jsonl /tmp/my_mattermost_export/export.jsoncd /home/zulip/deployments/current./scripts/stop-server./manage.py convert_mattermost_data /tmp/my_mattermost_export --output /tmp/converted_mattermost_data./manage.py import '' /tmp/converted_mattermost_data/<team-name>./scripts/start-serverunzip latest_export.zip -d /tmp/my_mattermost_exportmv /tmp/my_mattermost_export/import.jsonl /tmp/my_mattermost_export/export.jsoncd /home/zulip/deployments/current./scripts/stop-server./manage.py convert_mattermost_data /tmp/my_mattermost_export --output /tmp/converted_mattermost_data./manage.py import <subdomain> /tmp/converted_mattermost_data/<team-name>./scripts/start-server - Follow step 4 of the guide for installing a new Zulip server.
Import details
Section titled “Import details”Whether you are using Zulip Cloud or self-hosting Zulip, here are a few notes to keep in mind about the import process:
- Mattermost does not export workspace settings, so you will need to configure the settings for your Zulip organization. This includes settings like email visibility, message editing permissions, and how users can join your organization.
- Mattermost’s user roles are mapped to Zulip’s user
roles in the following way:
Mattermost role Zulip role Team administrator Owner Member Member - Mattermost’s export tool does not support exporting user avatars or message edit history.
- Direct messages will only be imported from Mattermost workspaces containing a single team. This is because Mattermost’s data exports do not associate direct messages with a specific Mattermost team.
- Messages in threads are imported, but they are not explicitly marked as being in a thread.
Get your organization started with Zulip
Section titled “Get your organization started with Zulip”Once the import process is completed, you will need to:
- Configure the settings for your organization, which are not exported. This includes settings like email visibility, message editing permissions, and how users can join your organization.
- All users from your previous workspace will have accounts in your new Zulip organization. However, you will need to let users know about their new accounts, and decide how they will log in for the first time.
- Share the URL for your new Zulip organization, and (recommended) the Getting started with Zulip guide.
- Migrate any integrations.
Decide how users will log in
Section titled “Decide how users will log in”When user accounts are imported, users initially do not have passwords configured. There are a few options for how users can log in for the first time.
Allow users to log in with non-password authentication
Section titled “Allow users to log in with non-password authentication”When you create your organization, users will immediately be able to log in with authentication methods that do not require a password. Zulip offers a variety of authentication methods, including Google, GitHub, GitLab, Apple, LDAP and SAML.
Send password reset emails to all users
Section titled “Send password reset emails to all users”You can send password reset emails to all users in your organization, which will allow them to set an initial password.
If you imported your organization into Zulip Cloud, simply email support@zulip.com to request this.
Send password reset emails (self-hosted organization)
Section titled “Send password reset emails (self-hosted organization)”- To test the process, start by sending yourself a password reset email by
using the following command:
./manage.py send_password_reset_email -u username@example.com
- When ready, send password reset emails to all users by
using the following command:
./manage.py send_password_reset_email -r '' --all-users
- To test the process, start by sending yourself a password reset email by
using the following command:
./manage.py send_password_reset_email -u username@example.com
- When ready, send password reset emails to all users by
using the following command:
If you would like to only send emails to users who have not logged in yet, you can use the following variant instead:./manage.py send_password_reset_email -r <subdomain> --all-users./manage.py send_password_reset_email -r <subdomain> --all-users --only-never-logged-in
Manual password resets
Section titled “Manual password resets”Alternatively, users can reset their own passwords by following the instructions on your Zulip organization’s login page.