Mattermost Recipe: Migrating off of Gitlab to Mattermost Enterprise Edition


You’re ready to upgrade to Mattermost Enterprise Edition but are running Mattermost with Gitlab Omnibus


1. Prepare your Gitlab Server

First, get your Gitlab server ready by making a backup. Then, configure PostgreSQL to listen on the right IP address.

1.1 Make a Backup

First thing to do is backup your Gitlab instance using the instructions here. If you haven’t already, set up automated backups as well.

1.2a Configure PostgreSQL for remote connections

If want to continue using the Gitlab Omnibus internal PostgreSQL server you’ll need to edit these lines of your gitlab.rb file to allow connections from outside IP addresses.

postgresql['listen_address'] = '*'
postgresql['trust_auth_cidr_addresses'] = ['', '']

Replace with the IP address of the server that will be hosting the Mattermost

1.2b Export Mattermost Database

If you want to move the Mattermost database to another server as well, export your data from the mattermost_production database using pg_dump, then import it using psql, e.g.:

# on the Gitlab server
pg_dump -U gitlab_mattermost -h mattermost_production > mattermost_production.sql
# on the new Mattermost PostgreSQL server
psql -U mmuser -h -f mattermost_production.sql

1.3 Disable Mattermost in Gitlab

In your gitlab.rb set these values to false:

  • mattermost['enable']
  • mattermost_nginx['enable']

Then run gitlab-ctl reconfigure

2. Install Mattermost EE on the other server

Next, install Mattermost Enterprise edition on the other server by following our instructions including setting up Nginx with TLS. Make sure that you install the enterprise edition so that you can install your license later.

3. Migrate Configuration and Data

These steps are for moving the data and configuration to a Mattermost instance on the same server. If Mattermost is going to be on another server the fastest way to do this is to first set up SSH key-based authentication between the Mattermost server and the Gitlab server .

3.1 Copy and Modify Config

First, make a copy of the Mattermost configuration file to make your edits:

sudo cp /var/opt/gitlab/mattermost/config.json /tmp/mattermost-config.json

Since Gitlab configures its Mattermost instance with environment variables, you’ll need to get those from the Mattermost process itself. To do that, first run ps ax | grep mattermost on the Gitlab server. Look for the line that ends with config.json to find the process ID:

12696 ?        SLsl   0:02 /opt/gitlab/embedded/bin/mattermost --config /var/opt/gitlab/mattermost/config.json

In this case, it’s 12696. Next, run this command - replacing 12696 with the process ID you found - to find the environment variables:

sudo strings /proc/12696/environ

Which will output something like this:

MM_SQLSETTINGS_DATASOURCE=user=gitlab_mattermost host=/var/opt/gitlab/postgresql port=5432 dbname=mattermost_production

Use the environment variable naming convention described under Environment Variables here to merge these with the config.json file.

3.2 Sync Data

If you’ve got Mattermost configured to use S3 or Minio, skip this step. If you’re using a network share you can skip it but make sure to configure the right path in the Mattermost configuration under FileSettings.Directory

sudo mkdir /opt/mattermost/data/
sudo rsync -aP /var/opt/gitlab/mattermost/data/ /opt/mattermost/data/

3.3 Sync Plugins

Plugins are synced using the same procedure as the data:

# First, empty the existing plugins directories
sudo rm /opt/mattermost/plugins/*
sudo rm /opt/mattermost/client/plugins/*

# Then, rsync both directories
sudo rsync -aP /var/opt/gitlab/mattermost/plugins/ /opt/mattermost/plugins/
sudo rsync -aP /var/opt/gitlab/mattermost/client-plugins/ /opt/mattermost/client/plugins/

4 Finish up

4.1 Test Mattermost

On your new server, run sudo systemctl start mattermost to enable it, then run curl to verify it’s working.

To test your Nginx configuration, use your hosts file to specify the hostname for your Mattermost server and connect to it in the browser. If you run into problems check your logs for relevant error messages.

Once you can log in, also try uploading files and using plugins to verify that everything is working.

4.1 Adjust DNS

Adjust your DNS records to set the A record for your Mattermost domain to the IP address of your new server Mattermost server, and your new Mattermost server is ready to go


Mattermost 5.27.0 allows those running Mattermost Team Edition, which comes with the Gitlab Omnibus, to upgrade to Enterprise Edition with just one click. While you can use this to upgrade to Mattermost EE, the enterprise binary will be overwritten when Gitlab Omnibus is upgraded, so you’ll have to upgrade again.

By following this procedure you have more control over the version of Mattermost server you’re running. Also, by extracting your Mattermost server you make it a lot easier to take advantage of High Availability to provide redundancy to your Mattermost instance. And you eliminate a single point of failure for your infrastructure. (How hard would it be to coordinate getting your Gitlab server back up without Mattermost?)

If you have specific questions about how to migrate your Mattermost Gitlab installation to another server in your application architecture leave a comment and we’ll be happy to help.