Mattermost is an open-source, self-hosted online chat service written in Go and JavaScript.


For this guide you should be familiar with the basic concepts of


You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
[isabell@stardust ~]$

Your URL needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
[isabell@stardust ~]$


Download the most recent Linux TAR archive from the Mattermost website:

[isabell@stardust ~]$ wget
--2019-12-23 13:27:01--
Resolving (,,, ...
Connecting to (||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 155306557 (148M) [application/x-gzip]
Saving to: ‘mattermost-5.18.0-linux-amd64.tar.gz’

100%[====================================================================>] 155,306,557 22.5MB/s   in 6.6s

2019-12-23 13:27:08 (22.6 MB/s) - ‘mattermost-5.18.0-linux-amd64.tar.gz’ saved [155306557/155306557]

[isabell@stardust ~]$

Extract the archive:

[isabell@stardust ~]$ tar xfv mattermost-5.18.0-linux-amd64.tar.gz
[isabell@stardust ~]$


Set up a Database

Run the following code to create the database <username>_mattermost in MySQL:

[isabell@stardust ~]$ mysql -e "CREATE DATABASE ${USER}_mattermost COLLATE utf8mb4_unicode_ci;"
[isabell@stardust ~]$

Change the configuration

You need to set up your URL, and MySQL settings in ~/mattermost/config/config.json.

First, set your site URL:

"SiteURL": ""

Then find the SqlSettings block and change the database driver to mysql, replace mmuser with your username, mostest with your MySQL password and isabell_mattermost with the name of the database you created earlier:

   "SqlSettings": {
     "DriverName": "mysql",
     "DataSource": "isabell:MySuperSecretPassword@tcp(localhost:3306)/isabell_mattermost?charset=utf8mb4,utf8\u0026readTimeout=30s\u0026writeTimeout=30s",
     "DataSourceReplicas": [],
     "DataSourceSearchReplicas": [],
     "MaxIdleConns": 20,
     "ConnMaxLifetimeMilliseconds": 3600000,
     "MaxOpenConns": 300,
     "Trace": false,
     "AtRestEncryptKey": "",
     "QueryTimeout": 30

Configure web server


Mattermost is running on port 8065.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Setup daemon

Create ~/etc/services.d/mattermost.ini with the following content:


After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING, check your configuration.

Setup a user

You can now point your browser to your URL and setup a user.

Further customisation

To further customise your configuration, you can open the system console in your browser and adapt any settings to your wishes. Setting the SMTP server is a good idea.



  1. Stop your service,

  2. Backup your directories
    • /home/isabell/mattermost/client/plugins,

    • /home/isabell/mattermost/config,

    • /home/isabell/mattermost/data,

    • /home/isabell/mattermost/logs

    • /home/isabell/mattermost/plugins

  3. Rename/delete your /home/isabell/mattermost directory.

  4. Proceed with the installation steps and restore the client/plugins, config, data, logs and plugins directories.

  5. Then you can start your service again.

When upgrading to Mattermost 6.4 or newer you need to change the collation of the database:

[isabell@stardust ~]$ mysql -e "ALTER DATABASE isabell_mattermost COLLATE = utf8mb4_general_ci;"
[isabell@stardust ~]$

Automatic Update

Use the script attached to update Mattermost to the current version. Run the script above the mattermost-root directory.

printf "\n===\nWelcome to updating Mattermost... let us begin!\n===\n"

printf "\n== Preflight Checks ==\n"
if [ ! -d "./mattermost" ]; then
printf "Error: ./mattermost directory does not exist. Are you running in the correct place?. Exit\n"
exit 1
        printf "Directory ./mattermost found.\n"

database=$(cat ./mattermost/config/config.json | jq '.SqlSettings.DataSource' | grep -o '/.*?' | tail -c +2 | head -c -2)
if [ -z "$database" ]
        printf "\nError: Could not extract the database name from ./mattermost/config/config.json. Maybe the script runs in the wrong directory? Exit 1.\n"
        exit 2
        printf "Using database: $database\n"

if [ -z "$version" ]
        printf "No manual version given. Check from official website ...\n"

        tag_name=$(curl -s | jq --raw-output '.tag_name')
        version=${tag_name:1} # This will remove the first character `v` from the version tag `v1.2.3`

        printf "Newest Version detected: v$version. For the changes introduced with this update see:\n"

usedVersion=$(./mattermost/bin/mattermost version | grep -Po "(?<=Version: )([0-9]|\.)*(?=\s|$)")
if [ "$usedVersion" = "$version" ]
        printf "\n=== You are up-to-date. No update needed. ===\n"
        exit 0

printf "\n== Prepare for takeoff ==\n"

printf "Downloading Version v$version...\n"

printf "\nExtracting Version ..."
tar -xf $mattermostfile --transform='s,^[^/]\+,\0-upgrade,'

printf "\nCreate Backup of filesystem..."
backupdir="mattermost-back-$(date +'%F-%H-%M')/"
cp -ra mattermost/ $backupdir

printf "\nCreate Backup of database: '$database' ..."
mysqldump --databases $database > $backupdir/$database.dump.sql

printf "\n== Take off ==\n"
printf "\nStop Service - ..."
supervisorctl stop mattermost

printf "\nDelete all old files ..."
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 | xargs rm -r

printf "\nApply new files ..."
cp -an mattermost-upgrade/. mattermost/

printf "\nStart Service again ..."
supervisorctl start mattermost

printf "\n== Take off complete ==\n"

printf "\nClean up files ..."
rm -r mattermost-upgrade/
rm -i mattermost*.gz

printf "\n===\nUpdate completed successfully.\n==="

Tested with Mattermost 7.7.1 and Uberspace 7.13.0

Written by: Nico Graf <>