Configuring Apache2 as a proxy for Mattermost Server

justinegeffen · July 20, 2021, 6:29pm

This unofficial guide is maintained by the Mattermost community and this deployment configuration is not yet officially supported by Mattermost, Inc. Community testing, feedback and improvements are welcome and greatly appreciated.

On a Debian-based operating system such as Ubuntu, Apache2 proxy configuration is done in the /etc/apache2/sites-available directory. Red Hat-based systems organize Apache configuration files differently. If you’re setting up Mattermost on a subdomain, you’ll want to create a new configuration file along the lines of mysubdomain.mydomain.com.conf.

To configure Apache2 as a proxy

SSH into your server.
Make sure the Apache modules mod_rewrite , mod_proxy, mod_proxy_http, and mod_proxy_wstunnel are installed and enabled. If not, follow the instructions from your Linux distribution to do so.
Create the above mentioned configuration file. It is often helpful to start with a copy of 000-default.conf or default-ssl.conf (on Ubuntu).
Edit your configuration using the guide below:
1. If you’re not setting up a subdomain, your ServerName will simply be set to mydomain.com.
2. ServerAlias can been added too if you want to capture www.mydomain.com.
3. Remember to change the values to match your server’s name, etc.
4. If you have enabled TLS in the Mattermost settings, you must use the protocol wss:// instead of ws:// in the RewriteRule.
5. To serve requests on a different port (such as 8443), in addition to setting the port in the VirtualHost element, add Listen 8443 on a separate line before the VirtualHost line.

		<VirtualHost *:80>
		  # If you're not using a subdomain you may need to set a ServerAlias to:
		  # ServerAlias www.mydomain.com
		  ServerName mysubdomain.mydomain.com
		  ServerAdmin hostmaster@mydomain.com
		  ProxyPreserveHost On

		  # Set web sockets
		  RewriteEngine On
		  RewriteCond %{REQUEST_URI} /api/v[0-9]+/(users/)?websocket [NC,OR]
		  RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC,OR]
		  RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
		  RewriteRule .* ws://127.0.0.1:8065%{REQUEST_URI} [P,QSA,L]

		  <Location />
			Require all granted
			ProxyPass http://127.0.0.1:8065/
			ProxyPassReverse http://127.0.0.1:8065/
			ProxyPassReverseCookieDomain 127.0.0.1 mysubdomain.mydomain.com
		  </Location>

		</VirtualHost>

(Debian/Ubuntu only) Because you’ll likely have not set up the subdomain before now on Apache2, run a2ensite mysubdomain.mydomain.com to enable the site (do not run a2ensite mysubdomain.mydomain.com.conf).
Restart Apache2.
- On Ubuntu 14.04 and RHEL 6: sudo service apache2 restart
- On Ubuntu 16.04+ and RHEL 7+: sudo systemctl restart apache2

You should be all set! Ensure that your Mattermost config file is pointing to the correct URL (which may include a port), and then ensure that your socket connection is not dropping once deployed. To prevent external access to Mattermost on port 8065, in the config file, set ListenAddress to localhost:8065 instead of :8065.

mallert · September 23, 2021, 11:45am

As suggested from the official mattermost community forum by Mattermost Carrie Warner, I am writing a reply for this howto as an addon to the (unofficial) CentOS Apache documentation. It could be put into a subcategory called “configuration apache and mattermost to be accessed in a sub-URL”.

CentOS/RHEL Linux Environment: How to set up mattermost in a sub-URL on your server and how to configure apache as a reverse proxy for it

Introduction

If you are using apache on your website as frontend webserver and you want to use mattermost, you will soon come into the problem, where the documentation tells you to configure apache with a subdomain instead of a sub-URL, e.g. if your website is https://www.example.com, the (unofficial) apache documentation suggests to address your mattermost installation with https://mattermost.example.com.

This can be a problem, if you are not the DNS master to add a new DNS record pointing to your new mattermost subdomain and you want to access mattermost within your website, e.g. https://www.example.com/mm. Or you will get in trouble issueing a new certificate for this new virtaul host. How to avoid that DNS and certificate problem? This is what this howto is about.

Mattermost configuration preparations

After you installed mattermost on you Linux box as already described in the regular documentation, you need to configure it, including database connection. After you have finished the initial configuration, we can continue accessing mattermost within your website URL. We also assume your mattermost installation on your Linux server is located at the path /opt/mattermost and you followed the recommendations to let mattermost only listen on the localhost port 8065, so it is not accessible directly outside your Linux server.

First of all we need to tell mattermost, how it will be adressed by which sub-URL in the config file. In this howto we choose to set the sub-URL to /mm.
For that, edit /opt/mattermost/config/config.json and set as SiteURL https://www.example.com/mm.

Don’t restart now, we need to add another crucial mattermost configuration.

Second, mattermost now knows it will be addressed by the URL https://www.example.com/mm. If you try to access it now, mattermost tries to get its static components like CSS and png from "/" and this leads to a “404 - Not found” error, because they cannot be found in the webservers document root. So instead we need to tell mattermost in its internal structures where to look for the static assets. We need to configure mattermost to address these static assets also at the sub-URL /mm.

This is done with the mattermost configuration tool mmctl:

cd /opt/mattermost/bin
./mmctl config subpath --assets-dir /opt/mattermost/client/ --path /mm

Now restart mattermost, if set up as systemd service, with the command service mattermost restart.

Mattermost is now ready to react to requests on your URL https://www.example.com/mm. But as it listens only to localhost or 127.0.0.1, now the apache reverse proxy configuration kicks in.

Apache reverse proxy configuration for mattermost

In your apache configuration, within your <VirtualHost>...</VirtualHost> configuration, create an include file or just enter the following relevant part in there:

# Include File for mattermost, let's call it mattermost-rv-proxy.conf
    ProxyPreserveHost On
    RewriteEngine On
    RewriteCond %{REQUEST_URI} /mm/api/v[0-9]+/(users/)?websocket [NC,OR]
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC,OR]
    RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
    RewriteRule .* ws://127.0.0.1:8065%{REQUEST_URI} [P,QSA,L]

    <Location /mm>
        Require all granted
        ProxyPass http://127.0.0.1:8065/mm
        ProxyPassReverse http://127.0.0.1:8065/mm
        ProxyPassReverseCookieDomain 127.0.0.1 www.example.com
    </Location>

Then include it in your VirtualHost configuration like:

<VirtualHost *:443>
    ServerName www.example.com
    ...
    Include /path-wherever-you-put-your-config-files/mattermost-rv-proxy.conf
    ...
</VirtualHost>

Or just put it directly into your Virtual Host configuration:

<VirtualHost *:443>
    ServerName www.example.com
    ...  
    ProxyPreserveHost On
    RewriteEngine On
    RewriteCond %{REQUEST_URI} /mm/api/v[0-9]+/(users/)?websocket [NC,OR]
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC,OR]
    RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
    RewriteRule .* ws://127.0.0.1:8065%{REQUEST_URI} [P,QSA,L]

    <Location /mm>
        Require all granted
        ProxyPass http://127.0.0.1:8065/mm
        ProxyPassReverse http://127.0.0.1:8065/mm
        ProxyPassReverseCookieDomain 127.0.0.1 www.example.com
    </Location>
    ...
</VirtualHost>

Please take a closer look at the rewrite condition for the API URL and the <Location /mm>. You see that everything belonging to our mattermost sub-URL is addressed as “/mm”, not only the frontend resources but also the mattermost backend. This is now mandatory because we told mattermost before in the SiteURL configuration how it is adressed and second that the static assets are also to be found within the sub-URL /mm.

Then restart apache with service httpd restart.

Voilà! Now you can address your mattermost installation with your browser at
https://www.example.com/mm.

This setup also works not only with your browser, but also with the iOS app and the Android app.

Best regards,

Martin

mallert · September 23, 2021, 1:48pm

My Howto for the sub-URL can also be applied to nginx - you only have to configure mattermost as in my howto and you need to adjust the mm urls in nginx.

rikrdo89 · March 4, 2023, 1:26pm

when a virtual host reverse proxy is configured for https (443) after running certbot anf getting a certificate, do I need to change the websocket protocol redirection to wss? or only change it in the app if we keep the http(80) virtual host only? Thanks

agriesser · March 4, 2023, 3:29pm

Hi @rikrdo89 and welcome to the Mattermost forums!

You do not need to change that to wss:// if your Mattermost application server is not running with SSL. If your Apache is doing the offloading, then you can leave the backend configuration like it is.

Please have a look at my current draft of the new version of this unofficial documentation and let me know if this would have helped you answer this question or if it should be more specific, so I can add that:

http://mattermost-docs-preview-pulls.s3-website-us-east-1.amazonaws.com/6249/configure/config-proxy-apache2.html

rikrdo89 · March 5, 2023, 4:21am

that looks great, thank you for your help and for improving the documentation. It looks better and now my mattermost server is up and running.

Couple of points:
“To serve requests on a different port (such as 8443)” → can you expand on this a little more? Do I ever need to listen to that port? under what circumstances? what features I am missing by not listening to that port?

Push notifications don’t seem to be working on my server jsut yet, and in the MM debugging log there is not even an entry for “[DEBG] Sending push notification” . IS there something that I may need to modify in my apache reverse proxy to allow “push” communications?

rikrdo89 · March 5, 2023, 3:38pm

I lied, I just needed to change some user settings to allow push notifications when online/away. Push notifications works!

rikrdo89 · March 6, 2023, 11:04pm

This line in the apache conf file proxy settings ( Apache2 < 2.4.47 ) results in an intermittent server disconnection error due to a web socket issue (as a red banner in the top of the webpage).

RewriteCond %{REQUEST_URI} /plugins/focalboard/ws/ [NC]

Removing that line, MM works without issues.

agriesser · March 7, 2023, 5:55am

Alright, thanks - I must admit that I did not test this configuration with Apache < 2.4.47 and just added the additional line, will do some further testing and also try to incorporate your points into the next draft version. Thanks!