# mattermost

<!-- metadata -->

* **Category**: Apps
* **Status**: 3
* **Image**: [`mattermost/mattermost-team-edition`](https://hub.docker.com/r/mattermost/mattermost-team-edition), 4, upstream
* **Healthcheck**: No
* **Backups**: Yes
* **Email**: 1
* **Tests**: 2
* **SSO**: No

<!-- endmetadata -->

## Basic usage

1. Set up Docker Swarm and [`abra`]
2. Deploy [`coop-cloud/traefik`]
3. `abra app new --secrets --app-name YOURAPPNAME mattermost` (optionally with `--pass` if you'd like
   to save secrets in `pass`)
4. `abra app config YOURAPPNAME` - be sure to change `$DOMAIN` to something that resolves to
   your Docker swarm box
5. `abra app deploy YOURAPPNAME`
6. Open the configured domain in your browser to finish set-up

## Enable Email
**WARNING: Following these steps will overwrite the configuration of your Mattermost instance. Probably only run it on a fresh deployment.**
- `abra app config YOURAPPNAME`
- Uncomment the section starting with **Email Support**
- `abra app secret i YOURAPPNAME smtp_pass v1 'yourSMTPpassword'`
- `abra app undeploy YOURAPPNAME`
- `abra app deploy YOURAPPNAME`
- `abra app command -C YOURAPPNAME app reset_config` <- This will overwrite your configuration

## Enable SSO with Authentik
This is how to configure your Mattermost server to accept logins from your Authentik SSO provider.

### Configure Authentik
#### Create a property mapping
- Log in as administrator of your Authentik instance
- Go to https://authentik.yourserver.org/if/admin/#/core/property-mappings and choose **Create**
- Choose Scope Mapping
   - Name: `Mattermost ID`
   - Scope Name: `id`
   - Description: *optional own description*
   - Expression: `return { "id": request.user.id }`
- Create another Scope Mapping
   - Name: `Mattermost Username`
   - Scope Name: `username`
   - Description: *optional own description*
   - Expression: `return { "username": request.user.username }`
#### Create Application and Provider
- Go to https://authentik.yourserver.org/if/admin/#/core/applications and choose **Create With Wizard**
   - Application Name: mattermost
   - **Next**
   - Choose OAuth2/OIDC
   - Set Authorization flow: `default-provider-authorization-implicit-consent (Authorize Application)`
   - Copy the **Client ID** and **Client Secret**, you'll need them later
   - Add Redirect URIs:
      - https://mattermost.yourserver.org/login/gitlab/complete
      - https://mattermost.yourserver.org/signup/gitlab/complete
   - Expand Advanced Protocol Settings
   - Under Scopes, select `Mattermost ID` and `Mattermost Username`, and click the > to add them to **Selected Scopes**
   - **Submit**

### Configure Mattermost
**WARNING: Following these steps will overwrite the configuration of your Mattermost instance. Probably only run it on a fresh deployment.**
- `abra app configure YOURAPPNAME`
   - Uncomment the section starting with `## SSO config`
   - Set `SSO_ID` to the value you saved when configuring Authentik
- `abra app secret insert YOURAPPNAME mattermost_sso_secret v1 <the authentik provider secret you saved>`
- `abra app undeploy YOURAPPNAME`
- `abra app deploy YOURAPPNAME`
- `abra app command -C YOURAPPNAME app reset_config` <- This will overwrite your configuration

### Disable non-SSO login (Optional)
- Ensure that your SSO user has the **System Admin** role: https://YOURAPPNAME/admin_console/user_management/users
- Go to https://YOURAPPNAME/admin_console/authentication/email
- Set **Enable sign-in with email** and **Enable sign-in with username** to `false`


[`abra`]: https://git.coopcloud.tech/coop-cloud/abra
[`coop-cloud/traefik`]: https://git.coopcloud.tech/coop-cloud/traefik