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 gitStep 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.
Check the installed version of docker.
$ docker -v
Docker version 24.0.5, build ced0996Now add your user to the Docker group.
sudo usermod -aG docker $USER
newgrp dockerProceed 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_64Move then docker-compose file to your PATH.
sudo mv docker-compose-linux-x86_64 /usr/local/bin/docker-composeNow you have successfully installed docker-compose on Linux. Verify this by checking the installed docker-compose version.
$ docker-compose version
Docker Compose version v2.21.0Start 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-dockerThe 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.ymlIn 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:roIn 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:
- ALLHere, 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 -dSeveral 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-1As 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 --reloadNow 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 nginxCreate a virtual host file.
sudo vim /etc/nginx/conf.d/mattermost.confIn 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.confNow edit the file at:
# CentOS / RHEL / Fedora
sudo vim /etc/nginx/nginx.conf
# Debian / Ubuntu
sudo vim /etc/nginx/sites-available/defaultComment 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 successfulStart and enable Nginx.
sudo systemctl start nginx
sudo systemctl enable nginxInstall 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-nginxThen proceed and install Trusted SSL Certificates on your domain name.
sudo certbot --nginxYou 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 CertbotIf 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 --reloadRestart Nginx.
sudo systemctl restart nginxThat 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 stopIf you want to remove the docker containers use the command
docker-compose stop && docker-compose rmConclusion
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:
