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'] = ['127.0.0.1/32', '10.0.2.2/32']
10.0.2.2 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
# on the Gitlab server pg_dump -U gitlab_mattermost -h 127.0.0.1 mattermost_production > mattermost_production.sql
# on the new Mattermost PostgreSQL server psql -U mmuser -h 127.0.0.1 -f mattermost_production.sql
1.3 Disable Mattermost in Gitlab
gitlab.rb set these values to
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:
OLDPWD=/opt/gitlab/sv/mattermost PATH=/opt/gitlab/bin:/opt/gitlab/embedded/bin:/usr/local/bin:/usr/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin PWD=/opt/gitlab/embedded/service/mattermost SSL_CERT_DIR=/opt/gitlab/embedded/ssl/certs/ MM_GITLABSETTINGS_SECRET=012c377d42f77a30231807939d02dffb9266c3be82c0fb97d052fa4f60aba86b MM_SERVICESETTINGS_SITEURL=http://mattermost.example.com MM_PLUGINSETTINGS_DIRECTORY=/var/opt/gitlab/mattermost/plugins MM_GITLABSETTINGS_TOKENENDPOINT=http://localhost/oauth/token MM_SERVICESETTINGS_LISTENADDRESS=127.0.0.1:8065 MM_GITLABSETTINGS_ENABLE=true MM_TEAMSETTINGS_SITENAME=GitLab Mattermost MM_LOGSETTINGS_FILELOCATION=/var/log/gitlab/mattermost MM_FILESETTINGS_DIRECTORY=/var/opt/gitlab/mattermost/data MM_GITLABSETTINGS_AUTHENDPOINT=http://localhost/oauth/authorize MM_PLUGINSETTINGS_CLIENTDIRECTORY=/var/opt/gitlab/mattermost/client-plugins MM_SQLSETTINGS_DATASOURCE=user=gitlab_mattermost host=/var/opt/gitlab/postgresql port=5432 dbname=mattermost_production MM_SERVICESETTINGS_ALLOWEDUNTRUSTEDINTERNALCONNECTIONS= localhost MM_GITLABSETTINGS_USERAPIENDPOINT=http://localhost/api/v4/user MM_GITLABSETTINGS_ID=fa11f0173e2ee56852d002fd7a5afed813fcc694caa968c5c2c2c752380b472d MM_SQLSETTINGS_ATRESTENCRYPTKEY=2d1de20e681b0c5eec0842663b75c703 MM_SERVICESETTINGS_ENABLEAPITEAMDELETION=true MM_SQLSETTINGS_DRIVERNAME=postgres GID=992 UID=992
Use the environment variable naming convention described under Environment Variables here to merge these with the
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
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 http://127.0.0.1:8065 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.