Upgrading Mattermost Server¶

Upgrading to the Latest Version¶

If you are upgrading from version 3.0 or later, these instructions apply to you. If you are upgrading from a version prior to 3.0.0, you must first upgrade to version 3.0.3.

Upgrading from a previous Extended Support Release to the latest Extended Support Release is supported. However, we strongly recommend that you review the Important Upgrade Notes for all intermediate versions in between to ensure you’re aware of the possible migrations that could affect your upgrade.

For High Availability deployments, we only support one minor version difference between server versions when performing a rolling upgrade. For example v5.27.1 + v5.27.2 or v5.26.4 + v5.27.1 is supported, whereas v5.25.5 + v5.27.0 is not supported. Running two different versions of Mattermost in your cluster should not be done outside of an upgrade scenario. In some upgrade scenarios, it won’t be possible to run different versions, and such cases are clearly noted in the Important Upgrade Notes product documentation.

Before you Begin¶

Read these instructions carefully from start to finish. Make sure that you understand each step before starting the upgrade. If you have questions or concerns, you can ask on the Mattermost forum at https://forum.mattermost.org/.

Upgrading Mattermost Server¶

1. In a terminal window on the server that hosts Mattermost, change to your home directory. Delete any files and directories that might still exist from a previous download.

   cd /tmp
   

2. Download the latest version of Mattermost Server. In the following command, replace X.X.X with the version that you want to download:

   wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz
   

3. Confirm no other Mattermost zip folders exist in your /tmp directory. If another version’s zip file does exist, delete or rename the file.

   ls -- mattermost*.gz
   

   If anything except the new release is returned above, rename this file or delete it completely.

4. Extract the Mattermost Server files.

   tar -xf mattermost*.gz --transform='s,^[^/]\+,\0-upgrade,'
   

   The transform option adds a suffix to the topmost extracted directory so it does not conflict with the usual install directory.

5. Stop your Mattermost server.

   sudo systemctl stop mattermost
   

6. Back up your data and application.

   1. Back up your database using your organization’s standard procedures for backing up MySQL or PostgreSQL.

   2. Back up your application by copying into an archive folder (e.g. mattermost-back-YYYY-MM-DD-HH-mm).

      cd {install-path}
      sudo cp -ra mattermost/ mattermost-back-$(date +'%F-%H-%M')/
      

7. Remove all files except data and custom directories from within the current mattermost directory.

   What’s preserved on upgrade?

   By default, your data directories will be preserved with the following commands:config, logs, plugins, client/plugins, and data (unless you have a different value configured for local storage). Custom directories are any directories that you’ve added to Mattermost and are not preserved by default. Generally, these are TLS keys or other custom information.

   Run ls on your Mattermost install directory to identify what default folders exist.

   A default Mattermost installation has the following files and directories:

   $ ls /opt/mattermost
   ENTERPRISE-EDITION-LICENSE.txt README.md  client  data   i18n  manifest.txt  prepackaged_plugins
   NOTICE.txt                      bin        config  fonts  logs  plugins       templates
   

   Clear the Mattermost folder

   Dry-run the following command to delete the contents of the mattermost folder, preserving only the specified directories and their contents:

   sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! \( -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data \) -prune \) | sort
   

   If you store TLSCert/TLSKey files or other information within your /opt/mattermost folder, you need to append -o -path mattermost/yourFolderHere to the command above to avoid having to manually copy the TLSCert/TLSKey files from the backup into the new install.

sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! \( -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data -o -path  mattermost/yourFolderHere \) -prune \) | sort

When you’re ready to execute the command, append xargs rm -r to the command above to delete the files. Note that the following example includes -o -path mattermost/yourFolderHere:

sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! \( -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data -o -path  mattermost/yourFolderHere \) -prune \) | sort | sudo xargs rm -r

Using Bleve Search

If using Bleve Search, and the directory exists within the mattermost directory, the index directory path won’t be preserved using the command above.

• You can either move the bleve index directory out from the mattermost directory before upgrading or, following an upgrade, you can copy the contents of the bleve index directory from the backup directory.

• You can then store that directory or re-index as preferred.

• The bleve indexes can be migrated without reindexing between Mattermost versions. See our Configuration Settings documentation for details on configuring the bleve index directory.

8. Copy the new files to your install directory and remove the temporary files.

sudo cp -an /tmp/mattermost-upgrade/. mattermost/
sudo rm -r /tmp/mattermost-upgrade/
sudo rm -i /tmp/mattermost*.gz

Note

The n (no-clobber) flag and trailing . on source are very important. The n (no-clobber) flag preserves existing configurations and logs in your installation path. The trailing . on source ensures all installation files are copied.

9. Change ownership of the new files after copying them. For example:

sudo chown -R mattermost:mattermost {install-path}

10. If you want to use port 80 or 443 to serve your server, and/or if you have TLS set up on your Mattermost server, you must activate the CAP_NET_BIND_SERVICE capability to allow the new Mattermost binary to bind to ports lower than 1024. For example:

cd {install-path}/mattermost
sudo setcap cap_net_bind_service=+ep ./bin/mattermost

11. Start your Mattermost server.

sudo systemctl start mattermost

12. If you’re using a High Availability deployment, you need to apply the steps above on every node in your cluster. Once complete, the Config File MD5 columns in the High Availability section of the System Console should be green. If they’re yellow, please ensure that all nodes have the same server version and the same configuration.

    If they continue to display as yellow, trigger a configuration propagation across the cluster by opening the System Console, changing a setting, and reverting it. This will enable the Save button for that page. Then, select Save. This will not change any configuration, but sends the existing configuration to all nodes in the cluster.

After the server is upgraded, users might need to refresh their browsers to experience any new features.

Upgrading Team Edition to Enterprise Edition¶

To upgrade from the Team Edition to the Enterprise Edition, follow the normal upgrade instructions provided above, making sure that you download the Enterprise Edition of Mattermost Server in Step 2.

Uploading a License Key¶

When Enterprise Edition is running, open System Console > About > Editions and License and upload your license key.