Install and Configure Mattermost Server on Amazon Linux 2

Posted on 275 views

Mattermost is a free and open-source chat and collaboration tool. Mattermost has many advantages as an online chat and collaboration tool such as integration with other online tools, configurable bots for custom workflows and many more. This tool is popular with DevOps tools such as Git.

This guide will cover how to install Mattermost on Amazon Linux 2. We will also use Nginx as a reverse proxy and Let’s Encrypt SSL for encryption of the server’s HTTP traffic.

Mattermost Architecture

Mattermost works in a server-client architecture where the server contains the chat engine and the clients connect to the server using either mobile phone applications or web browsers.

Mattermost is compiled as a single Go binary configured using the config.json file. The file provides the following:

  • Authentication client: The functionality for users to log into Mattermost via email address and password in Team Edition. Enterprise Edition E10 adds the ability for users to authenticate using Active Directory or LDAP, and Enterprise Edition E20 adds the ability to authenticate using SAML SSO providers like ADFS, OneLogin, and Okta.
  • Authentication provider: Enables the Mattermost server to authenticate to other services like GitLab and Zapier using OAuth 2.0.
  • Data management service: Connects to supported databases and file storage solutions (local, network-attached storage, Amazon S3, etc), and manages the reading and writing of data between them.
  • Proxy: You can configure Mattermost to work behind a proxy, like Nginx. This gives you the advantage of encrypting your platform traffic using SSL.
  • Push notification service: Mattermost has a hosted push notification service that can push notifications to mobile clients, send SMTP notifications.

Setup Pre-requisites

Before we can install Mattermost on Amazon Linux 2, ensure your system has minimal requirements. System hardware requirements vary depending on the maximum users intended for the platform. This is as shown below:

  • 1 – 1,000 users – 1 vCPU/cores, 2 GB RAM
  • 1,000 – 2,000 users – 2 vCPUs/cores, 4 GB RAM

For users of more than 2000, it is recommended you use the load testing tool available on GitHub to determine the minimal requirements required for your system.

Install and Configure Mattermost on Amazon Linux 2

Follow the steps below to install Mattermost on Amazon Linux 2 with Let’s Encrypt.

Step 1. Update system

Update your Amazon Linux instance and reboot

sudo yum -y update
sudo reboot

Step 2. Install and Configure Database Server

Install MariaDB server on Amazon Linux. Mattermost supports both MySQL server and Postgres SQL server. In this guide, we shall use the open-source version of MySQL server, MariaDB.

sudo yum -y install @mariadb
sudo systemctl enable --now mariadb

Harden MariaDB server

[root@amazon-linux ~]# sudo mysql_secure_installation


In order to log into MariaDB to secure it, we'll need the current
password for the root user.  If you've just installed MariaDB, and
you haven't set the root password yet, the password will be blank,
so you should just press enter here.

Enter current password for root (enter for none): 
OK, successfully used password, moving on...

Setting the root password ensures that nobody can log into the MariaDB
root user without the proper authorisation.

Set root password? [Y/n] y
New password: 
Re-enter new password: 
Password updated successfully!
Reloading privilege tables..
 ... Success!

By default, a MariaDB installation has an anonymous user, allowing anyone
to log into MariaDB without having to have a user account created for
them.  This is intended only for testing, and to make the installation
go a bit smoother.  You should remove them before moving into a
production environment.

Remove anonymous users? [Y/n] y
 ... Success!

Normally, root should only be allowed to connect from 'localhost'.  This
ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] y
 ... Success!

By default, MariaDB comes with a database named 'test' that anyone can
access.  This is also intended only for testing, and should be removed
before moving into a production environment.

Remove test database and access to it? [Y/n] y
 - Dropping test database...
 ... Success!
 - Removing privileges on test database...
 ... Success!

Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.

Reload privilege tables now? [Y/n] y
 ... Success!

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

Configure a database user and create the Mattermost database.

$ mysql -u root -p
GRANT ALL PRIVILEGES ON mattermost.* TO [email protected] IDENTIFIED BY 'Str0ngPassw0rd';

Step 3. Install Mattermost on Amazon Linux 2

Add a system user that will be used to manage the Mattermost service.

sudo useradd -d /opt/mattermost -U -M mattermost

Download and install the latest version of Mattermost from the Mattermost download page. At the time of writing this article, the latest version of Mattermost is 6.x.


Extract the downloaded archive.


tar xvf mattermost-6.0.1-linux-amd64.tar.gz

Move the extracted files to the /opt directory.

sudo mv mattermost /opt

Create the data directory for files and images that users will post on the platform.

sudo mkdir /opt/mattermost/data

Set the right permissions to the files

sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost

Configure the Database driver.

sudo vim /opt/mattermost/config/config.json

At the “Sqlsettings” section, we need to configure Mattermost to use MySQL and also configure the database credentials.

  • Set the “DriverName” to mysql
  • Configure the “DataSource” in the format "mmuser:@tcp(:3306)/mattermost?charset=utf8mb4,utf8&readTimeout=30s&writeTimeout=30s"

where mmuser: is the db_user:db_user-password details we created in step 2.

My configuration looks like this below:

        "DriverName": "mysql",
        "DataSource": "mattermost:Str0ngPassw0rd@tcp(localhost:3306)/mattermost?charset=utf8mb4,utf8\u0026readTimeout=30s\u0026writeTimeout=30s",
        "DataSourceReplicas": [],
        "DataSourceSearchReplicas": [],
        "MaxIdleConns": 20,
        "ConnMaxLifetimeMilliseconds": 3600000,
        "MaxOpenConns": 300,
        "Trace": false,
        "AtRestEncryptKey": "",
        "QueryTimeout": 30

Step 4. Start Mattermost Server

After the above configuration, start the Mattermost server. Navigate to the Mattermost working directory.

cd /opt/mattermost

Start the Mattermost server as below:

$ sudo -u mattermost ./bin/mattermost
"level":"info","ts":1629019440.0392742,"caller":"app/server.go:269","msg":"Server is initializing...","go_version":"go1.15.5"
"level":"info","ts":1629019440.0393405,"caller":"app/web_hub.go:93","msg":"Starting websocket hubs","number_of_hubs":2
"level":"info","ts":1629019440.0397189,"caller":"i18n/i18n.go:93","msg":"Loaded system translations","for locale":"en","from locale":"/opt/mattermost/i18n/en.json"
"level":"info","ts":1629019440.0487335,"caller":"sqlstore/store.go:306","msg":"Pinging SQL","database":"master"
"level":"info","ts":1629019440.056872,"caller":"sqlstore/store.go:306","msg":"Pinging SQL","database":"migrations"
"level":"info","ts":1629019440.1456177,"caller":"app/server.go:579","msg":"Enterprise Build","enterprise_build":true
"level":"info","ts":1629019440.145637,"caller":"app/server.go:585","msg":"Printing current working","directory":"/opt/mattermost"
"level":"info","ts":1629019440.1456475,"caller":"app/server.go:586","msg":"Loaded config","source":"file:///opt/mattermost/config/config.json"
"level":"info","ts":1629019440.152936,"caller":"jobs/workers.go:135","msg":"Starting workers"
"level":"info","ts":1629019440.1530619,"caller":"jobs/schedulers.go:116","msg":"Starting schedulers."
"level":"info","ts":1629019440.161364,"caller":"mlog/log.go:237","msg":"Starting up plugins"
"level":"info","ts":1629019440.1614122,"caller":"app/plugin.go:258","msg":"Syncing plugins from the file store"
"level":"info","ts":1629019442.7709634,"caller":"app/license.go:88","msg":"License key from required to unlock enterprise features."
"level":"info","ts":1629019443.1491122,"caller":"mlog/sugar.go:21","msg":"Ensuring Surveybot exists","plugin_id":"com.mattermost.nps"
"level":"info","ts":1629019443.3604462,"caller":"app/server.go:1179","msg":"Starting Server..."
"level":"info","ts":1629019443.3606062,"caller":"app/server.go:1255","msg":"Server is listening on [::]:8065","address":"[::]:8065"

Verify that the server has started successfully:

[[email protected] ~]# ss -plunt | grep 8065
tcp    LISTEN   0        128                     *:8065                *:*       users:(("mattermost",pid=4841,fd=34)) 

Step 5. Configure Mattermost Service

Create a Mattermost service unit file to enable us manage the service using systemd.

sudo tee /etc/systemd/system/mattermost.service<

Set SELinux to permissive:

sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/g' /etc/selinux/config

Reload systemd daemon then start Mattermost service.

sudo systemctl daemon-reload
sudo systemctl enable --now mattermost

Verify the service status:

[root@amazon-linux ~]# systemctl status mattermost.service 
● mattermost.service - Mattermost
   Loaded: loaded (/etc/systemd/system/mattermost.service; enabled; vendor preset: disabled)
   Active: active (running) since Sun 2021-08-15 09:25:57 UTC; 14s ago
 Main PID: 5027 (mattermost)
   CGroup: /system.slice/mattermost.service
           ├─5027 /opt/mattermost/bin/mattermost
           ├─5049 plugins/com.mattermost.plugin-channel-export/server/dist/plugin-linux-amd64
           ├─5054 plugins/com.mattermost.nps/server/dist/plugin-linux-amd64
           └─5059 plugins/com.mattermost.plugin-incident-management/server/dist/plugin-linux-amd64

Aug 15 09:25:54 amazon-linux mattermost[5027]: "level":"info","ts":1629019554.3931122,"caller":"app/plugin.go:258","msg":"Syncing plugins from the file store"
Aug 15 09:25:57 amazon-linux mattermost[5027]: "level":"info","ts":1629019556.999772,"caller":"app/license.go:88","msg":"License key from required to unlock enterprise features."
Aug 15 09:25:57 amazon-linux mattermost[5027]: "level":"error","ts":1629019557.2133331,"caller":"app/server.go:1679","msg":"Failed to send notifications to admin users.","error":"GetWarnMetrics... is empty., "

Step 6. Install and Configure Nginx Proxy

Install Nginx webserver to use it as a reverse proxy and also for Let’s Encrypt SSL configuration.

To install Nginx, we need to have Epel-release available on our Amazon Linux 2 instance.

sudo dnf -y install epel-release
sudo dnf -y install nginx

Start and enable Nginx service

sudo systemctl enable --now nginx

Configure Nginx to work as a reverse proxy. Create a configuration file in the Nginx conf.d directory.

sudo vi /etc/nginx/conf.d/mattermost.conf

Paste the content below in the file. Replace with your FQDN.

upstream backend 
   keepalive 32;

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;

   listen 80;

   location ~ /api/v[0-9]+/(users/)?websocket$ 
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       client_max_body_size 50M;
       proxy_set_header Host $http_host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Frame-Options SAMEORIGIN;
       proxy_buffers 256 16k;
       proxy_buffer_size 16k;
       client_body_timeout 60;
       send_timeout 300;
       lingering_timeout 5;
       proxy_connect_timeout 90;
       proxy_send_timeout 300;
       proxy_read_timeout 90s;
       proxy_pass http://backend;

   location / 
       client_max_body_size 50M;
       proxy_set_header Connection "";
       proxy_set_header Host $http_host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Frame-Options SAMEORIGIN;
       proxy_buffers 256 16k;
       proxy_buffer_size 16k;
       proxy_read_timeout 600s;
       proxy_cache mattermost_cache;
       proxy_cache_revalidate on;
       proxy_cache_min_uses 2;
       proxy_cache_use_stale timeout;
       proxy_cache_lock on;
       proxy_http_version 1.1;
       proxy_pass http://backend;

Verify that the Nginx configuration is okay.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart Nginx service

sudo systemctl restart nginx

Enable HTTP and HTTPS service through the firewall.

sudo firewall-cmd --add-service=http,https --permanent
sudo firewall-cmd --reload

Step 7. Configure Mattermost Server

Open the domain configured on Nginx, e.g:


Configure and admin user to manage the Mattermost platform.


Create a team for your Mattermost platform


Assign the team a name then proceed to the Mattermost dashboard.


The dashboard looks like this below.


You can now add or invite users to the platform using the admin console.


The users will use the link to join the platform. You can now start conversations with the newly added users.


Users can use the application clients available for different platforms such as Android and iOS.

Step 8. Configure Let’s Encrypt SSL Certificate

We will use the open-source Let’s Encrypt SSL certificate with certbot.

Obtain Let’s Encrypt certbot as shown below:

sudo amazon-linux-extras install epel -y
sudo yum -y install certbot

Stop Nginx service.

sudo systemctl stop nginx

Obtain SSL cert, issuing your FQDN.

export DOMAIN=""
export EMAIL_ALERTS="[email protected]"
sudo certbot certonly --standalone -d $DOMAIN --preferred-challenges http --agree-tos -n -m $EMAIL_ALERTS --keep-until-expiring

Update the Nginx configuration with the ssl cert information.

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;

   listen 80 default_server;
   return 301 https://$server_name$request_uri;

server {
  listen 443 ssl http2;

  ssl on;
  ssl_certificate /etc/letsencrypt/live/domain-name/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/domain-name/privkey.pem;
  ssl_session_timeout 1d;
  ssl_protocols TLSv1.2;
  ssl_prefer_server_ciphers on;
  ssl_session_cache shared:SSL:50m;
  # HSTS (ngx_http_headers_module is required) (15768000 seconds = 6 months)
  add_header Strict-Transport-Security max-age=15768000;
  # OCSP Stapling ---
  # fetch OCSP records from URL in ssl_certificate and cache them
  ssl_stapling on;
  ssl_stapling_verify on;

  location ~ /api/v[0-9]+/(users/)?websocket$ {
    proxy_set_header Upgrade $http_upgrade;

location / {
    proxy_http_version 1.1;

Restart Nginx service.

sudo systemctl restart nginx

You can now use HTTPS to access your Mattermost dashboard.


That’s it, as far as Mattermost deployment on Amazon Linux 2 is concerned. Feel free to get on touch in case you encounter any issues during your deployment. Cheers!


Gravatar Image
A systems engineer with excellent skills in systems administration, cloud computing, systems deployment, virtualization, containers, and a certified ethical hacker.