This article is about installing mattermost behind a OPNsense reverse proxy using Ubuntu 22 (Jammy) LTS and the official Omnibus deployment method of Mattermost.

Prerequirements

• A new Ubuntu Server 22.04 (Jammy)(min. 1 CPU and 2 GB RAM). At time of writing Ubuntu Server 23 (Mantic) is not supported by Omnibus.
• All OS updates installed
• A (sub-)domain where Mattermost will be reachable at (i.e. Mattermost.reukauff.eu).
• OPNsense with the nginix und let’s encrypt plugin installed in front of the new Ubuntu server.

Install Mattermost

This is the most easy part of the whole setup. Run this commands to add the Mattermost repository to the local repositories and run the installation. The second command installs Mattermost without Let’s encrypt as we will use OPNsense for the HTTPS certificate stuff:

curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash
sudo MMO_HTTPS=false apt install mattermost-omnibusrr

During the installation Omnibus will ask you for a domain name. Enter the domain name, you will use for Mattermost (i.e. mattermost.reukauff.eu). It also asks for the mail address for Let’s Encrypt. Enter a mailaddress, but a certificate will not being requested as we run the setup without HTTPS setup.

After the setup completed run the following command to open the configuration:

sudo mmctl --local config edit

A vi-editor opens. Search for the line AllowCorsFrom. Press i to change to edit mode of the vi editor. Change the value to *.

"AllowCorsFrom":"*"

Press Ctrl+C followed by typing :wq and press Enter. The editor closes and you should see the line Config updated successfully after some seconds. Now we need to enable plugin uploads. Run

sudo nano /etc/mattermost/mmomni.yml

Change the value for enable_plugin_uploads to true and save the file with Ctrl+O and quit with Ctrl+X Finally reload Mattermost by run

sudo mmomni reconfigure

Mattermost is now setup and you can reach it already internally via http://yourserver:8065.

Setup OPNsense

Now the real pain starts as Mattermost is using many special settings in the nginx configuration. A blueprint of this settings can be found here in the Mattermost documentation: Set up an NGINX proxy — Mattermost documentation

With the following setup we get as close as possible to the nginx config Mattermost describes in their documentation.

• In OPNsense go to Services > ACME Client > Settings > Accounts
• Create a new entry. Enter for example the following settings:
  • Enabled: enable
  • Name: the (sub-)domain you use for your Mattermost site. (i.e. mattermost.reukauff.eu)
  • Description: Any description you like
  • E-Mail Address: Your e-mail address
  • ACME CA: Let's Encrypt [default]
• Save the new account and in the linke of the account at the right click on the Register Account button.
• After some seconds the column Registration Date should have the current timestamp. The account is registered now.
• In OPNsense go to Services > ACME Client > Settings > Certificates. Create a new entry with the following settings:
  • Enabled: enable
  • Common Name: Your (sub-)domain of Mattermost
  • ACME Account: the account just created before
  • Automations: Restart Nginx
• Save the new certificate request and click on the Issue or renew certificate button at the right of your new certificate.
• In OPNsense go to Services>Nginx>Configuration
• If not already done, enable nginx on the General Settings Tab Cache Path. Create a new entry with the following settings:
  • Path: /var/cache/nginx
  • Size (MB): 10
  • Inactive Time (Minutes): 120
  • Use Temp Path: disable
  • Maximum Size (GB): 3
• Now click on the small triangle next to the HTTP(S) tab title and select Security Headers. Add a new entry with the following settings at the General tab:
  • Description: HSTS Age 15768000 or similar
  • Time (Max Age): 15768000
• Now click on the small triangle next to the HTTP(S) tab title and select ``
• Change to Upstream Server by click on the Upstream tab. Create a new Upstream and set a Description (i.e. the server name of the Mattermost server), the Server IP address and the port to 8065. The port 8065 is the port where the Mattermost application is running natively via HTTP:
• Click the small triangle next to the Upstream tab title and select Upstream form the menu. Add a new Upstream. Enter a description (i.e. Mattermost) and select your Upstream Server in the combobox at Server Entries. Save the settings.
• Go to the HTTP(S) tab. Create a new entry on that tab (it’s the Location page). At the very top enable the advanced mode. Set the following settings:
  • Description: Mattermost Main (or similar)
  • URL Pattern: /
  • Upstream Servers: The previously created upstream server
  • Cache: Directory: the previously created cache directory
  • Force HTTPS: enable
  • Enable HTTP/2 Preloading: enable
• Add another entry with the following settings:
  • Description: Mattermost Websocket (or similar)
  • URL Pattern: api/v[0-9]+/(users/)?websocket$
  • Match Type: Case Sensitive Match ("~")
  • Upstream Servers: Mattermost
  • Force HTTPS: enable
  • Enable HTTP/2 Preloading: enable
• Now click on the small triangle next to the HTTP(S) tab title and select HTTP Server. Create a new entry with the following settings:
  • Enable advanced mode at the very top left
  • HTTP Listen Address: 80
  • HTTPS Listen Address: 443
  • Server Name: your (Sub-)Domain where Mattermost should be reachable at (i.e. mattermost.reukauff.eu)
  • Locations: Mattermost Main and Mattermost Websocket (or whatever you called it)
  • TLS Certificate: The certificate configured before
  • Client CA Certificate: R3 (ACME Client)
  • Zero RTT: enable
  • Enable Let’s Encrypt Plugin support: enable
  • Prefer server ciphers: enable
  • OCSP Stapling: enable
  • OCSP Verify: enable
  • Header Buffer Size (kB): 1
  • Count Of Large Header Buffers: 4
  • Size Of Large Header Buffers (kB): 8
  • Security Header: The created security Header
• After that you need to allow port 80 and 443 in the firewall. Otherwise it is blocked and will not even reach the reverse proxy on OPNsense.
• And finally, you must configure a NAT (“Port forwarding”) for port 8443 UDP and TCP to the Mattermost server. This is required to enable the connections for calls.
• That’s it. Mattermost is running now and OPNsense is acting as reverse proxy and also handles the Let’s encrypt certificates. You can access Mattermost now on your configured (Sub-)domain, create the first user and configure your server.

Configure Mattermost

When connecting to Mattermost and login using the initially created user, there are some minor things to configure, you should configure to have a full featured environment.

Configure mail settings

At the very top left click on the tiles-button and select System Console. In the System Console on the left select SMTP. Configure your Mailserver settings in this dialog. They are individual for each setup, so I cannot make recommendations regarding the setting except that you should use a dedicated mail address for Mattermost.

Push Notification Server

By default push notifications to the Apps are disabled. To enable them, in the System Console go to Mobile push notifications. Select the setting Use TPNS connection to send notifications to iOS and Android app. Note: This is only recommended for non-critical environments as the TPNS service (“Test Push Notification Service) does not offer any SLAs. In worst case the notifications are send with a huge delay or never. If you have a critical environment, check the Hosted Push Notifications Service (HPNS) of Mattermost.

Localization

If you want other languages to be available for your users than your default language you can go to Localization in the System Console. Here you can select the default Server and Client language as well as additional languages available for your clients. Note: If nothing is selected at Available Languages all languages are available!

Registration / Signup

By default everyone can create new accounts on your server that get an invite from another user. At Signup in the System Console you can change this behavior to be more strict (i.e. users cannot invite or limit registration on defined domains) or more relaxed (everyone can register without invitation).

References

Install Mattermost via Omnibus: Install Mattermost Omnibus — Mattermost documentation Mattermost Calls documentation: Calls self-hosted deployment — Mattermost documentation Mattermost Mobile Push documentation: Mobile push notifications — Mattermost documentation