##########
Mattermost
##########

`Mattermost <https://mattermost.org>`__ 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.

.. code-block:: JavaScript

    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:

.. code-block:: JSON

    {
        "....": {},
        "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:

.. code-block:: console

    [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:

.. code-block:: mysql

    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:

.. code-block:: console

    [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``:

.. code-block:: ini

    [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:

.. code-block:: console

    [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:

.. code-block:: console

    [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