Mattermost

Mattermost is a messaging and workflow management service. It is based on nodejs. On the server, you can reach it at https://mattermost.falken-niedersachsen.de.

SAML Connection

SAML Auth is a enterprise feature in mattermost. However, Mattermost offers GitLab SSO in the Community Edition. We use Keycloak to mimic the GitLab SSO Authentication. The OIDConnect client settings in Keycloak are:

• Settings:

  • Client Protocol: openid-connect

  • Access Type: confidental

  • Standard Flow Enabled: true

  • Valid Redirect URL: https://mattermost.falken-niedersachsen.de/signup/gitlab/complete

  • Base URL: https://mattermost.falken-niedersachsen.de

• Credentials:

  • Client Authenticator: Client Id and Secret

• Mappers:

  • name, Full Name Mapper, mapping to name (Add to userinfo is enabled)

  • username: User Property Mapper, mapping username property to username string token claim (Add to userinfo is enabled)

  • email: User Property Mapper, mapping email property to email string token claim (Add to userinfo is enabled)

  • id: Script Mapper, mapping to id long token claim (Add to userinfo is enabled). This is needed because mattermost expects a unique id number for every SAML user. Remember to activate Script Mappers when using this.

function getRandomId() {
    return Math.floor(Math.random() * 9223372036854775807).toString(10);
}

if(user.getFirstAttribute("mattermostid")) {
    exports = user.getFirstAttribute("mattermostid")
} else {
    var new_id = getRandomId();
    // make sure the id is unique
    while(keycloakSession.users().searchForUserByUserAttribute("mattermostid", new_id, realm).length > 0) {
        new_id = getRandomId();
    }
    user.setSingleAttribute("mattermostid", new_id);
    exports = new_id;
}

In the mattermost config, set the following settings:

{
    "....": {},
    "GitLabSettings": {
        "Enable": true,
        "Secret": "{Secret from the Credentials Tab in the Keycloak Client Settings}",
        "Id": "mattermost",
        "Scope": "",
        "AuthEndpoint": "https://keycloak.falken-niedersachsen.de/auth/realms/FalkenNiedersachsen/protocol/openid-connect/auth",
        "TokenEndpoint": "https://keycloak.falken-niedersachsen.de/auth/realms/FalkenNiedersachsen/protocol/openid-connect/token",
        "UserAPIEndpoint": "https://keycloak.falken-niedersachsen.de/auth/realms/FalkenNiedersachsen/protocol/openid-connect/userinfo",
        "DiscoveryEndpoint": "",
        "ButtonText": "Falken NDS Account",
        "ButtonColor": "#c95d5c"
    },
    "....": {}
}

Setup

While mattermost and its database lives on the SSD (volume local-zfs), the files are supposed to be saved to the HDDs (volume data-pool). To achieve that, mount a subvolume at /var/mattermost-data.

To setup, first install nodejs (on Debian, for Version 12 LTS a different repositiory is needed) and the other dependecies:

[root@mattermost: ~] $ apt update; apt install curl sudo
[root@mattermost: ~] $ curl -sL https://deb.nodesource.com/setup_12.x -o nodesource_setup.sh # Setup nodejs 12 repository
[root@mattermost: ~] $ nano nodesource_setup.sh # Be sure to inspect the file to not run something fishy
[root@mattermost: ~] $ bash nodesource_setup.sh
[root@mattermost: ~] $ curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | tee /usr/share/keyrings/yarnkey.gpg >/dev/null # Setup yarn package manager
[root@mattermost: ~] $ echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | tee /etc/apt/sources.list.d/yarn.list
[root@mattermost: ~] $ apt install nodejs yarn
[root@mattermost: ~] $ apt install mariadb-server mariadb-client # Setup Maria DB

Then, setup a database for mattermost:

CREATE DATABASE mattermost COLLATE utf8mb4_unicode_ci;
CREATE USER mattermost IDENTIFIED BY '{secret}';
GRANT ALL PRIVILEDGES ON mattermost.* TO mattermost;
FLUSH PRIVILEGES;

Download mattermost and copy it to the /opt/ directory:

[root@mattermost: ~] $ wget https://releases.mattermost.com/{version}/mattermost-{version}-linux-amd64.tar.gz
[root@mattermost: ~] $ tar -xvzf mattermost*.gz
[root@mattermost: ~] $ mv mattermost /opt
[root@mattermost: ~] $ useradd --system --user-group mattermost
[root@mattermost: ~] $ chown -R mattermost:mattermost /opt/mattermost
[root@mattermost: ~] $ chmod -R g+w /opt/mattermost
[root@mattermost: ~] $ chown -R mattermost:mattermost /var/mattermost-data # Set permissions for the data directory
[root@mattermost: ~] $ mkdir -p /var/log/mattermost # Setup log dir

Configure the installation /opt/mattermost/config/config.json:

1. Set "DriverName" to "mysql"

2. Set "DataSource" to "mattermost:{secret}@tcp(localhost:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s"

3. Set FileSettings.Directory to /var/mattermost-data/

4. Test the server sudo -u mattermost bin/mattermost

Install a systemd service running mattermost. For that, create a systemd service config in, e.g. /etc/systemd/system/mattermost.service:

[Unit]
Description=Mattermost
After=network.target
After=mysqld.service
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=mattermost
ExecStart=/opt/mattermost/bin/mattermost
StandardOutput=/var/log/mattermost/stdout.log
StandardError=/var/log/mattermost/sterr.log

[Install]
WantedBy=multi-user.target

Complete the setup by start the service:

[root@mattermost: ~] $ systemctl enable mattermost
[root@mattermost: ~] $ systemctl start mattermost

Mattermost should then be running at localhost:8065.

Upgrade

The upgrade process is very similar to the installation process minus a few steps:

[root@mattermost: ~] $ mysqldump mattermost > mattermost-database-$(date +'%F-%H-%M').sql # Backup database
[root@mattermost: ~] $ mkdir -p tmp; cd tmp/
[root@mattermost: ~/tmp] $ rm mattermost*.gz
[root@mattermost: ~/tmp] $ wget https://releases.mattermost.com/6.1.0/mattermost-6.1.0-linux-amd64.tar.gz
[root@mattermost: ~/tmp] $ tar -xf mattermost*.gz --transform='s,^[^/]\+,\0-upgrade,'
[root@mattermost: ~/tmp] $ cd /opt/
[root@mattermost: /opt/] $ systemctl stop mattermost
[root@mattermost: /opt/] $ cp -ra mattermost/ mattermost-back-$(date +'%F-%H-%M')/
[root@mattermost: /opt/] $ # Delete everyting except for user settings
[root@mattermost: /opt/] $ 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 | sudo xargs rm -r
[root@mattermost: /opt/] $ cp -an /root/mattermost-upgrade/. mattermost/
[root@mattermost: /opt/] $ chown -R mattermost:mattermost mattermost
[root@mattermost: /opt/] $ systemctl start mattermost