Mattermost installation: The important details for sysadmins

January 8, 2020

Platform

ChatOps is about bringing conversations, tools, files, and automation into a single space.

Mattermost has a number of plugins that support ChatOps and real-time DevOps workflows through integrations with developer tools like Jira, GitLab, GitHub, Bitbucket, and Jenkins.

At the core is the Mattermost Server.

Visit the Integrations Directory to see all integrations.

Mattermost Server is a single Linux binary with a core set of functionalities for:

Exposing a RESTful JSON web service
Connectivity to a database and file storage
Authentication with an email address, AD/LDAP, or SSO, depending on the edition, including OAuth 2.0 against other services like GitLab
Notifications via SMTP and push services to mobile apps

The Mattermost team has worked hard to make the installation and setup of an open source enterprise-scale application impressively simple.

What follows is a concise account of the requirements and processes needed to install Mattermost so that you can easily plan what resources you need to stand up and how much time it’s going to take.

Supported clients

There are lots of ways for users to interact with Mattermost.

Desktop support

Native apps for MacOS, Windows, and Ubuntu Linux (and RHEL/CentOS 7+ unofficially)
Web support for Firefox, Safari, Chrome, and Edge
Email support for Outlook, Apple Mail, and Thunderbird

Mobile support

Native apps available for Android and iOS
Push notification support
Web support for Chrome and Safari browser apps
Email support for iOS Mail and Gmail App

A number of web-based email clients are also supported. See all current software requirements.

Server requirements

The minimum requirements for a single-server install include:

A supported Linux operating system installed on a server
The Mattermost binary
A database
A filestore

It is also recommended to put a reverse proxy in front of Mattermost for security (managing the SSL layer), performance, mapping port 80 to 8065, and logging. Setting up TLS (Transport Layer Security) on Mattermost is the easiest option. But only consider this where there are less than 200 users (see TLS setup).

Supported operating systems	Community supported operating systems	Supported databases
Ubuntu 16.04 and 18.05	Fedora	MySQL 5.6, 5.7, 8
Debian Buster	FreeBSD	PostgreSQL 9.4+
CentOS 6+ and 7+	Arch Linux	Amazon Aurora MySQL 5.6+
RedHat Enterprise Linux 6+ and 7+		(Check the limitations of each database.)
Oracle Linux 6+ and 7+

And for the reverse proxy:

Supported proxies	Unofficially supported proxies
NGINX	Apache2

Installation and setup of NGINX for Mattermost is covered in the installation documentation.

Docker is fully supported and is the recommended, simple, one-line installation, using the Mattermost Docker images for both quick preview on a single machine and multiple machines with Docker Compose.

Example hardware scenario: Team of 100 software developers

In this scenario, Mattermost is used for text-based communication and notifications from source control and build pipelines. It’s also used for very occasional sharing of Microsoft Word documents (check out the Mattermost Collabora plugin) and small image files.

A typical back-end shopping list for this scenario would be for a single-server solution such as:

1x vCPU/core
2 GB RAM
6.5 GB storage (estimated to cater for the first year, calculated based on 100 developers)

See a detailed guide to estimating disk storage requirements.

Example hardware scenario: Team of 1,000 with mixed functions, tech industry

In this scenario, Mattermost is used across all organization teams for text-based communication, sharing images such as screenshots and Microsoft Office documents—but rarely anything bigger than 5 MB.

A typical back-end shopping list for this scenario would be for a single-server solution such as:

2x vCPUs/cores
4 GB RAM
350 GB storage (estimated to cater for the first year with a 2x safety factor)

Example hardware scenario: Teams larger than 2,000

For most small to medium teams, such as those in the scenarios above, a single-server install is sufficient.

For large teams, explore the option of Enterprise Edition multi-server deployments, where additional system requirements are recommended.

Larger setups have other considerations, such as switching out the software proxy server for a hardware proxy which would also serve as a load balancer.

To give you an idea of how well Mattermost can scale, it has been load tested with 60,000 concurrent users with:

Six Mattermost servers: m4.2xlarge (8 vCPU, 32 GB RAM)
One MySQL database server with five read replicas: db.r4.2xlarge (8 vCPU, 61 GB RAM)
Three load test runners (for running the load test)
Three NGINX proxies

Any deployments for teams larger than 2,000 should be load tested, which can be completed with the open source framework from Mattermost.

A five-step installation

A summary of tasks required to get up and running with a single-server install are as follows.

See here for full details of all installation steps.

1. Prepare the server platform

As per the architectural requirements above:

Provision the server and install a supported Linux version.
Provision a supported version of either MySQL or PostgreSQL.
Provision a file store (local storage may be adequate or else consider NAS or Amazon S3).

2. Set up the database

Install database software on the server.
Create the database.
Create the user account and grant it privileges.

3. Install Mattermost

Download the latest binary for your version of Linux.
Install it to /opt.
Add a user at the operating system level and it grant permissions to the folder.
Create the config file and edit the database settings. At this point, you can test it. It should be listening on port 8065.
Set up Mattermost as a service with systemd.

4. Configure Mattermost

Follow the instructions on the website for creating a System Admin account. Set all the essential configuration options to get started:

Site URL
Email notifications
File storage location

All configuration settings are detailed in the Administrator’s Guide.

5. Configure TLS

As mentioned, you can set up TLS on the Mattermost server itself when catering for less than 200 users but the recommendation is still a reverse proxy in all production settings.

Install an NGINX server.
Configure the NGINX server as the proxy for the Mattermost server.

Full guidance is provided in the Mattermost documentation.

Other considerations

There are a couple of other things to consider when planning your Mattermost deployment.

1. Network access

Mattermost is intended to sit within a private network. If outside access is required, then a VPN (virtual private network) is recommended. If you intend to leave Mattermost accessible to the open internet, see the additional guidance on a non-VPN setup.

2. Push notifications to the mobile apps

In order to push to mobile apps, a post notification service (or proxy server) is required, which will relay messages through to Apple and Google’s services. You can set one up yourself or use the one hosted by Mattermost.

3. Hosted by Mattermost

This is included with Enterprise Edition E10 subscriptions or above. See setup instructions for more information.

Self-Hosted

If you host your own push notification server, you will need to compile the iOS and Android apps yourself because the push service needs knowledge of the secret compiled into the app. The self-compile process is documented here.

Next Steps

Fire up a VM and follow the installation instructions to try it out today.

I was able to set up a fully functional Mattermost Server in under an hour and—take my word for it—I’m an awful sysadmin!

(Editor’s note: This post was written by Ben Hall, Expert .NET Software Engineer at the United Kingdom Hydrographic Office. If you have any feedback or questions about Mattermost installation: The important details for sysadmins, please let us know.)