Mattermost Upgrade Guide

Upgrading Mattermost to Next Major Release

Each release of Mattermost contains logic to upgrade it from the previously major build version. For example, version 1.2 upgrades the database and configuration data schema for a Mattermost version 1.1 server. The following procedure outlines how to upgrade Mattermost to the next major release version.

  1. Download the next major build release of your server
  2. Determine the current version of your Mattermost server
    1. Go to any team site, opening the main menu at the top right of the left-hand sidebar and selecting About Mattermost
  3. Identify the next major build release of your Mattermost server from the list of stable Mattermost releases
    1. For example, if your current version is 1.1.0, you want to select version 1.2.0.
    2. In some cases there will be minor build releases, such as 1.2.1 and 1.2.2. The minor build number indicates a bug fix or security issue release. Testing on minor build versions is less extensive than on major build versions and it is recommended that you use the minor build only if you need the specific additions included.
  4. Review Release Notes
    1. Check the release notes for the version of Mattermost you are able to install, and note any setting changes in the Compatibility section that apply to your deployment
  5. Download the mattermost.tar.gz file with the correct version for your upgrade
    1. You can use wget to retrieve a specific version. For example, to download v1.1.0 run wget https://github.com/mattermost/platform/releases/download/v1.1.0/mattermost.tar.gz
  6. Stop the Mattermost Server
  7. As best practice, consider posting to the Town Square channel of active teams pre-announcing the scheduled downtime to apply these upgrade procedures
  8. To stop the server run sudo stop mattermost
  9. Backup your data
  10. Back up your config.json file, which contains your system configuration. This will be used to restore your current settings after the new version is installed
  11. Backup your database using your organization's standard procedures for backing up MySQL or PostgreSQL
  12. If you're using local file storage, back up the location where files are stored
  13. Decompress mattermost.tar.gz and use its contents to replace the current version of Mattermost on disk
  14. Run tar -xvzf mattermost.tar.gz
  15. Restore the state of your server by copying the backed up version of config.json in place of the default config.json
  16. Start your server and address any setting changes relevant in the latest version of Mattermost
  17. Run sudo start mattermost
  18. The server will upgrade your database schema to be compatibile with the new release, as well as upgrade your config.json file to the latest format, using default values for new settings added
  19. Go to the System Console to update any settings that have been added or modified based on the Compatibility documentation in the release notes
  20. Test the system is working by going to the URL of an existing team

Upgrading from Mattermost Beta (Version 0.7)

The following instructions apply to updating installations of Mattermost v0.7-Beta to Mattermost 1.1.

Upgrading Mattermost in GitLab 8.0 to GitLab 8.1 with omnibus

Mattermost 0.7.1-beta in GitLab 8.0 was a pre-release of Mattermost and Mattermost v1.1.1 in GitLab 8.1 was updated significantly to get to a stable, forwards-compatible platform for Mattermost.

The Mattermost team didn't think it made sense for GitLab omnibus to attempt an automated re-configuration of Mattermost (since 0.7.1-beta was a pre-release) given the scale of change, so we're providing instructions for GitLab users who have customized their Mattermost deployments in 8.0 to move to 8.1:

  1. Follow the Upgrading Mattermost v0.7.1-beta to v1.1.1 instructions below to identify the settings in Mattermost's config.json file that differ from defaults and need to be updated from GitLab 8.0 to 8.1
  2. Upgrade to GitLab 8.1 using omnibus, and allowing it overwrite config.json to the new Mattermost v1.1.1 format
  3. Manually update config.json to new settings identified in Step 1

Optionally, you can use the new System Console user interface to make changes to your new config.json file.

Upgrading Mattermost v0.7.1-beta to v1.1.1

Note: Mattermost v1.1.1 is a special release of Mattermost v1.1 that upgrades the database to Mattermost v1.1 from EITHER Mattermost v0.7 or Mattermost v1.0. The following instructions are for upgrading from Mattermost v0.7.1-beta to v1.1.1 and skipping the upgrade to Mattermost v1.0.

If you've manually changed Mattermost v0.7.1-beta configuration by updating the config.json file, you'll need to port those changes to Mattermost v1.1.1:

  1. Go to the config.json file that you manually updated and note any differences from the default config.json file in Mattermost 0.7.

  2. For each setting that you changed, check the changelog documentation on whether the configuration setting has changed between v0.7 and v1.1.1

  3. Update your new config.json file in Mattermost v1.1, based on your preferences and the changelog documentation above

Optionally, you can use the new System Console user interface to make changes to your new config.json file.