How To Run Mattermost Server in Docker Containers

Welcome to this guide on how to run Mattermost Server in Docker Containers. Mattermost is a free tool used to establish a connection between an individual and groups. It is one of the biggest competitors of messaging platforms such as MS Teams and Slack. It can establish communication in form of chats, video calls, or normal voice calls.

Mattermost is preferred over other messaging platforms since it is easy to install and configure and can be hosted on a private cloud.

Features of Mattermost are:

• File Sharing
• Third Party Integrations
• Incident resolution – resolves incidents quicky and thus saving on time.
• Document Storage
• Data Import and Export
• Workflow management and orchestration.
• Drag & Drop
• Application and network performance monitoring.
• IT Service desk
• Document Storage
• Alerts/Notifications

Setup Requirements

For this guide you need the following:

• Docker and Docker-compose
• A Fully Qualified Domain Name, this will be required for generating SSL certificates.

Install the required packages.

## On RHEL/CentOS/RockyLinux 8
sudo yum update
sudo yum install curl vim git

## On Debian/Ubuntu
sudo apt update && sudo apt upgrade
sudo apt install curl vim git

## On Fedora
sudo dnf update
sudo dnf -y install curl vim git

Step 1 – Install Docker and Docker-Compose

Before we begin on Mattermost installation, ensure that docker and docker-compose are installed on your Linux system.

Install the latest Docker version on Linux using the guide below.

• How To Install Docker CE on Linux Systems

Check the installed version of docker.

$ docker -v
Docker version 20.10.10, build c2ea9bc

Now add your user to the Docker group.

sudo usermod -aG docker $USER
newgrp docker

Proceed and install the latest version of Docker-compose on your Linux system.

curl -s https://api.github.com/repos/docker/compose/releases/latest | grep browser_download_url  | grep docker-compose-linux-x86_64 | cut -d '"' -f 4 | wget -qi -

Make the file executable as below.

chmod +x docker-compose-linux-x86_64

Move then docker-compose file to your PATH.

sudo mv docker-compose-linux-x86_64 /usr/local/bin/docker-compose

Now you have successfully installed docker-compose on Linux. Verify this by checking the installed docker-compose version.

$ docker-compose version
Docker Compose version v2.1.1

Start and enable docker to run on boot.

sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER
newgrp docker

Step 2 – Provision the Mattermost Server

In this guide, we will have a total of 3 docker containers i.e web application, database, and the Mattermost server containers

Create local volume directories to store data.

sudo mkdir -pv /srv/mattermost/volumes/app/mattermost/{data,logs,config,plugins,client-plugins}
sudo chown -R 2000:2000 /srv/mattermost/

Now clone the Mattermost git repo.

git clone https://github.com/mattermost/mattermost-docker.git 
cd mattermost-docker

The docker-compose.yml file has 3 parts, the database, the Mattermost server, and the web application.

Open the YAML file and exit the 3 parts as below:

vim docker-compose.yml

In the file, make the below changes.

1. Configure Database Container

Now edit the database container configuration replacing appropriately.

.......
db:
    build: db
    read_only: true
    restart: unless-stopped
    volumes:
      - /srv/mattermost/var/lib/postgresql/data:/var/lib/postgresql/data
      - /etc/localtime:/etc/localtime:ro
    environment:
      - POSTGRES_USER=mmuser
      - POSTGRES_PASSWORD=Passw0rd
      - POSTGRES_DB=mattermost
........

In the command, replace PassW0rd with your preferred password for the PostgreSQL database to be created.

2. Configure the Mattermost Server Container

Now we will proceed in the same YAML file and provision the container for the Mattermost Server.

.......
  app:
    build:
      context: app
      # uncomment following lines for team edition or change UID/GID
      args:
          - edition=team
            #  - PUID=1000
            # - PGID=1000
            # - MM_VERSION=5.31
            # restart: unless-stopped
    volumes:
      - /srv/mattermost/volumes/app/mattermost/config:/mattermost/config:rw
      - /srv/mattermost/volumes/app/mattermost/data:/mattermost/data:rw
      - /srv/mattermost/volumes/app/mattermost/logs:/mattermost/logs:rw 
      - /srv/mattermost/volumes/app/mattermost/plugins:/mattermost/plugins:rw
      - /srv/mattermost/volumes/app/mattermost/client-plugins:/mattermost/client/plugins:rw
      - /etc/localtime:/etc/localtime:ro

In the above code, set the edition to be downloaded to “team“, also set the volumes to the local volume created as above.

Also, proceed and enter details for your database environment for the Mattermost server to connect to your database as below.

........
    environment:
      # set same as db credentials and dbname
      - MM_USERNAME=mmuser
      - MM_PASSWORD=Passw0rd
      - MM_DBNAME=mattermost

      # use the credentials you've set above, in the format:
      # MM_SQLSETTINGS_DATASOURCE=postgres://${MM_USERNAME}:${MM_PASSWORD}@db:5432/${MM_DBNAME}?sslmode=disable&connect_timeout=10
      - MM_SQLSETTINGS_DATASOURCE=postgres://mmuser:Passw0rd@db:5432/mattermost?sslmode=disable&connect_timeout=10
........

3. Configure the web container

The remaining part in the YAM file is to provision the web container.

............
 web:
    build: web
    ports:
      - "8001:8080"
      - "4430:8443"
    read_only: true
    restart: unless-stopped
    volumes:
      # This directory must have cert files if you want to enable SSL
      # - ./volumes/web/cert:/cert:ro
      - /etc/localtime:/etc/localtime:ro
    cap_drop:
      - ALL

Here, we want the web service to be mapped on ports 8001 and 4430 since we will be running our reverse proxy server later.

Now you will have your docker-compose.yml file ready. Initialize the containers as below.

$ docker-compose up -d

Several images will be pulled as shown.

=> [mattermost-docker_db 3/5] RUN apk add --no-cache       build-base   122.2s
 => => #   Preparing metadata (setup.py): finished with status 'done'          
 => => # Collecting envdir                                                     
 => => #   Downloading envdir-1.0.1-py2.py3-none-any.whl (13 kB)               
 => => # Collecting gevent>=1.0.2                                              
 => => #   Downloading gevent-21.8.0.tar.gz (6.2 MB)                           
 => => #   Installing build dependencies: started                              
 => [mattermost-docker_web  5/11] RUN chown -R nginx:nginx /etc/nginx/sit  1.0s
 => [mattermost-docker_web  6/11] RUN touch /var/run/nginx.pid &&          1.0s
 => [mattermost-docker_web  7/11] COPY ./security.conf /etc/nginx/conf.d/  0.3s
 => [mattermost-docker_web  8/11] RUN chown -R nginx:nginx /etc/nginx/con  1.3s
 => [mattermost-docker_web  9/11] RUN chmod u+x /entrypoint.sh             1.4s
 => [mattermost-docker_web 10/11] RUN sed -i "/^http {/a \    proxy_buffe  1.4s
.......                                     

Once completed, check the containers as below.

$ docker ps 
CONTAINER ID   IMAGE                   COMMAND                  CREATED          STATUS                    PORTS                                                                                  NAMES
d38f28337916   mattermost-docker_db    "/entrypoint.sh post…"   40 seconds ago   Up 38 seconds (healthy)   5432/tcp                                                                               mattermost-docker-db-1
5c4c668d4122   mattermost-docker_app   "/entrypoint.sh matt…"   40 seconds ago   Up 38 seconds (healthy)   8000/tcp                                                                               mattermost-docker-app-1
376062c0a2be   mattermost-docker_web   "/entrypoint.sh"         40 seconds ago   Up 38 seconds (healthy)   0.0.0.0:8001->8080/tcp, :::8001->8080/tcp, 0.0.0.0:4430->8443/tcp, :::4430->8443/tcp   mattermost-docker-web-1

As seen from the output, we have 3 containers running i.e web, database, Mattermost server.

Step 3 – Access Mattermost Web Interface

Now everything is set up, allow port 8001 through the firewall.

sudo firewall-cmd --add-service=8001 --permanent
sudo firewall-cmd --reload

Now proceed and access the Mattermost Web Interface on your browser using the URL http://domain-name:8001 or http://IP_Address:8001

Create an account for the Mattermost server and proceed to the Mattermost dashboard.

While here, you can proceed to create a team and begin your conversation or proceed to the System console where you make admin changes to your server. The system console looks like this.

Create a team for communication.

When done, you will have your Mattermost ready as below.

Step 4 – Setup reverse proxy and SSL (Optional)

Accessing the Mattermost site via HTTP is not secure enough, we need to secure this site by installing SSL certificates. For the purposes of this guide, I will use Nginx as the reverse proxy server.

Install Nginx Web server as below.

##On RHEL/CentOS/Rocky Linux 8
sudo yum install nginx

##On Debian/Ubuntu
sudo apt install nginx

Create a virtual host file.

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

In the conf file, add the below lines.

    server {
        listen       80 default_server;
        listen       [::]:80 default_server;
        server_name  mattermost.example.com;
        root         /usr/share/nginx/html;

        # Load configuration files for the default server block.
        include /etc/nginx/default.d/*.conf;

        location / {
	proxy_pass http://localhost:8001/;
            index  index.html index.htm;
        }

        error_page 404 /404.html;
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
    }

Grant privileges of the created file to Nginx.

# CentOS / RHEL / Fedora
sudo chown nginx:nginx /etc/nginx/conf.d/mattermost.conf
sudo chmod 755 /etc/nginx/conf.d/mattermost.conf

# Debian / Ubuntu
sudo chown www-data:www-data /etc/nginx/conf.d/mattermost.conf
sudo chmod 755 /etc/nginx/conf.d/mattermost.conf

Now edit the file at:

# CentOS / RHEL / Fedora
sudo vim /etc/nginx/nginx.conf 

# Debian / Ubuntu
sudo vim /etc/nginx/sites-available/default

Comment out the server part in the conf file. Check the syntax of the created file.

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

Start and enable Nginx.

sudo systemctl start nginx
sudo systemctl enable nginx

Install SSL certificates with Let’s Encrypt.

With Let’s Encrypt, one can install trusted SSL certificates for free on any FQDN. First, you need to install Certbot.

##On RHEL 8/CentOS 8/Rocky Linux 8/Fedora
sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm 
sudo dnf install certbot python3-certbot-nginx

##On Debian/Ubuntu
sudo apt install certbot python3-certbot-nginx

Then proceed and install Trusted SSL Certificates on your domain name.

sudo certbot --nginx

You will proceed as below.

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Enter email address (used for urgent renewal and security notices)
 (Enter 'c' to cancel): Enter a valid Email address here          

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing, once your first certificate is successfully issued, to
share your email address with the Electronic Frontier Foundation, a founding
partner of the Let's Encrypt project and the non-profit organization that
develops Certbot? We'd like to send you email about our work encrypting the web,
EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
Account registered.

Which names would you like to activate HTTPS for?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: mattermost.example.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel): 1

Requesting a certificate for mattermost.example.com
Performing the following challenges:
http-01 challenge for mattermost.example.com
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /etc/nginx/conf.d/mattermost.conf
Redirecting all traffic on port 80 to ssl in /etc/nginx/conf.d/mattermost.conf

Successfully received certificate.
Certificate is saved at: a2enmod ssl
/etc/letsencrypt/live/mattermost.example.com/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/mattermost.example.com/privkey.pem
This certificate expires on 2022-01-09.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
 * Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
 * Donating to EFF:                    https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

You will now have your Certificates installed successfully and added to your conf file as below.

$ sudo cat /etc/nginx/conf.d/mattermost.conf
.............
    listen [::]:443 ssl ipv6only=on; # managed by Certbot
    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/mattermost.example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/mattermost.example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
    server {
    if ($host = mattermost.example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


        listen       80 default_server;
        listen       [::]:80 default_server;
        server_name  mattermost.example.com;
    return 404; # managed by Certbot

If you are using Firewald, allow HTTP and HTTPS through the firewall.

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

Restart Nginx.

sudo systemctl restart nginx

That is it! Proceed and access the Mattermost server page using HTTPS with the URL https://domain_name. You should see the page secure as below.

As seen from the above output, the site is secure.

Stopping / Removing Mattermost containers

You can stop the containers using the command:

docker-compose stop

If you want to remove the docker containers use the command

docker-compose stop && docker-compose rm

Conclusion

This is the end! I hope you learned a lot from this guide on how to run Mattermost Server in Docker Containers. We have gone further to demonstrate how to secure your site with SSL Certificates.

See more on this page: