Mattermost is an open-source messaging platform that offers a variety of features such as chatting, file-sharing, project management, and workflow orchestration. It is written in Go language and is available as both a cloud-hosted solution and a self-hosted server. By hosting Mattermost on your server, you gain control over your communications and sensitive data, making it an ideal alternative to platforms like Slack. In this comprehensive guide, we will walk you through the process of installing and configuring Mattermost Team Messaging System on a Ubuntu 22.04 server.
Prerequisites
Before we begin, make sure you have the following:
- A server running Ubuntu 22.04 with a minimum of 2 GB of RAM for up to 1000 users.
- A non-root user with sudo privileges.
- The Uncomplicated Firewall (UFW) enabled and running.
- A fully qualified domain name (FQDN) pointed to your server. For the purpose of this tutorial, we will be using the domain mattermost.example.com.
- Ensure that your server is up to date by running the following commands:
sudo apt update && sudo apt upgrade
Step 1 – Configure Firewall
The first step before installing any packages is to configure the firewall to allow HTTP and HTTPS connections. Start by checking the status of the firewall:
sudo ufw status
You should see the following output:
Status: active To Action From -- ------ ---- OpenSSH ALLOW Anywhere OpenSSH(v6) ALLOW Anywhere(v6)
To allow Mattermost to function properly, we need to open port 8065 temporarily. We will remove this rule later on. Run the following command to allow port 8065:
sudo ufw allow 8065
Next, allow HTTP and HTTPS ports:
sudo ufw allow http sudo ufw allow https
Verify the changes by checking the firewall status:
sudo ufw status
The output should now include the following lines:
Status: active To Action From -- ------ ---- OpenSSH ALLOW Anywhere 80/tcp ALLOW Anywhere 443 ALLOW Anywhere 8065 ALLOW Anywhere OpenSSH (v6) ALLOW Anywhere (v6) 80/tcp (v6) ALLOW Anywhere (v6) 443 (v6) ALLOW Anywhere (v6) 8065 (v6) ALLOW Anywhere (v6)
Step 2 – Install PostgreSQL
Mattermost can work with both MySQL and PostgreSQL servers, but PostgreSQL is the recommended choice. Ubuntu 22.04 ships with the latest stable version of PostgreSQL (v14). Install PostgreSQL by running the following command:
sudo apt install postgresql postgresql-contrib
To check the installed version, run:
psql --version
The output should resemble the following:
psql (PostgreSQL) 14.4 (Ubuntu 14.4-0ubuntu0.22.04.1)
Step 3 – Configure PostgreSQL
During the installation of PostgreSQL, a Linux user account named “postgres” is created. We will use this account to access the PostgreSQL shell. Log in to the PostgreSQL shell by running the following command:
sudo -u postgres psql
Inside the PostgreSQL shell, create a new database for Mattermost:
CREATE DATABASE mattermostdb;
Next, create a new user for the Mattermost database. Replace ‘mmuser-password’ with a strong password of your choice:
CREATE USER mmuser WITH PASSWORD 'mmuser-password';
Grant all privileges on the database to the user:
GRANT ALL PRIVILEGES ON DATABASE mattermostdbTO mmuser;
Exit the PostgreSQL shell by entering q
.
Next, we need to modify the PostgreSQL configuration file to allow connections from Mattermost. Open the file /etc/postgresql/{version}/main/pg_hba.conf
for editing:
sudo nano /etc/postgresql/{version}/main/pg_hba.conf
Find the following lines:
# "local" is for Unix domain socket connections only local all all peer # IPv4 local connections: host all all127.0.0.1/32 scram-sha-256 # IPv6 local connections: host all all::1/128 scram-sha-256
Change the values peer
and scram-sha-256
to trust
in the above lines:
# "local" is for Unix domain socket connections only local all all trust # IPv4 local connections: host all all127.0.0.1/32 trust # IPv6 local connections: host all all::1/128 trust
Save the file by pressing Ctrl + X and entering Y when prompted. Restart the PostgreSQL service to apply the changes:
sudo systemctl restart postgresql
To verify that you can connect to the Mattermost SQL user, run the following command:
psql --dbname=mattermostdb --username=mmuser --password
You will be prompted for the password. Enter the password and you should be logged in to the PostgreSQL shell. Enterq
to exit the shell.
Step 4 – Download Mattermost
Next, we need to download the latest version of the Mattermost server. At the time of writing this tutorial, the latest available version is 7.0.1. Run the following command to download the archive:
wget https://releases.mattermost.com/7.0.1/mattermost-7.0.1-linux-amd64.tar.gz
Extract the downloaded archive:
tar -xvzf mattermost*.gz
Move the extracted files to the /opt
directory:
sudo mv mattermost /opt
Create the data storage directory for the Mattermost server:
sudo mkdir /opt/mattermost/data
Step 5 – Create a System user for Mattermost and configure permissions
Now, we need to create a system user and group specifically for the Mattermost server. This will ensure that the server runs with the appropriate permissions. Run the following command to create the user and group:
sudo useradd --system --user-group mattermost
Change the ownership of the Mattermost directory to the newly created user and group:
sudo chown -R mattermost:mattermost /opt/mattermost
Give write permissions to the Mattermost group on the directory:
sudo chmod -R g+w /opt/mattermost
Switch to the Mattermost directory:
cd /opt/mattermost
Start the Mattermost server as the mattermost user:
sudo -u mattermost./bin/mattermost
The server will start and generate a log of information. Wait for the line “Server is listening on [::]:8065” to appear.
Step 6 – Create a Systemd unit file
To ensure that the Mattermost server starts automatically on server boot, we need to create a Systemd unit file. Create and open the unit file for editing:
sudo nano /lib/systemd/system/mattermost.service
Paste the following code into the file:
[Unit]
Description=Mattermost
After=network.target
After=postgresql.service
BindsTo=postgresql.service
[Service]
Type=notify
ExecStart=/opt/mattermost/bin/mattermost
TimeoutStartSec=3600
KillMode=mixed
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost
LimitNOFILE=49152
[Install]
WantedBy=multi-user.target
Save the file by pressing Ctrl + X and entering Y when prompted.
Reload the systemd daemon to load the service file:
sudo systemctl daemon-reload
Start the Mattermost service:
sudo systemctl start mattermost
Check the status of the service:
sudo systemctl status mattermost
If everything is configured correctly, the output should indicate that the service is active and running.
Enable the service to start on boot:
sudo systemctl enable mattermost
Step 7 – Install Nginx
Ubuntu 22.04 ships with an older version of Nginx. To install the latest version, we need to download the official Nginx repository. Follow these steps to install Nginx:
Import Nginx’s signing key:
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
Add the repository for Nginx’s stable version:
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \| sudo tee /etc/apt/sources.list.d/nginx.list
Update the system repositories:
sudo apt update
Install Nginx:
sudo apt install nginx
Verify the installation:
nginx -v
The output should display the installed version of Nginx.
Step 8 – Install SSL
To secure your Mattermost installation, we need to install an SSL certificate. In this tutorial, we will use Certbot, a tool for automatically obtaining and renewing SSL certificates. Follow the steps below to install Certbot:
sudo snap install core sudo snap install --classic certbot sudo ln -s /snap/bin/certbot /usr/bin/certbot
Once Certbot is installed, generate an SSL certificate by running the following command:
sudo certbot certonly --standalone --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m test@example.com -d mattermost.example.com
Replace mattermost.example.com
with your domain name. Certbot will download the certificate and store it in the /etc/letsencrypt/live/mattermost.example.com
directory on your server.
Next, generate a Diffie-Hellman group certificate:
sudo openssl dhparam-dsaparam -out /etc/ssl/certs/dhparam.pem 4096
Open the file /etc/letsencrypt/renewal/mattermost.example.com.conf
for editing:
sudo nano /etc/letsencrypt/renewal/mattermost.example.com.conf
Add the following pre-hook and post-hook commands at the bottom of the file:
pre_hook = systemctl stop nginx post_hook = systemctl start nginx
Save the file by pressing Ctrl + X and entering Y when prompted.
To check if the SSL renewal process is working correctly, perform a dry run:
sudo certbot renew --dry-run
If there are no errors, your certificate will be automatically renewed in the future.
Step 9 – Configure Nginx
With Nginx installed and the SSL certificate generated, we can now configure Nginx to work with Mattermost. Open the file /etc/nginx/nginx.conf
for editing:
sudo nano /etc/nginx/nginx.conf
Add the following line before the line include /etc/nginx/conf.d/*.conf;
:
server_names_hash_bucket_size 64;
Save the file by pressing Ctrl + X and entering Y when prompted.
Create a new Nginx configuration file for Mattermost:
sudo nano /etc/nginx/conf.d/mattermost.conf
Paste the following configuration into the file, replacing mattermost.example.com
with your domain name:
upstream backend { server 127.0.0.1:8065; 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; server { listen 80 default_server; server_name mattermost.example.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name mattermost.example.com; http2_push_preload on; # Enable HTTP/2 Server Push ssl_certificate /etc/letsencrypt/live/mattermost.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/mattermost.example.com/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/mattermost.example.com/chain.pem; ssl_session_timeout 1d; # Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC). ssl_protocols TLSv1.2 TLSv1.3; # Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to # prevent replay attacks. # @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data ssl_early_data on; ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384'; ssl_prefer_server_ciphers on; ssl_session_cache shared:SSL:50m; # HSTS (ngx_http_headers_module is required) (15768000 seconds = six 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; ssl_dhparam /etc/ssl/certs/dhparam.pem; add_header X-Early-Data $tls1_3_early_data; 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_http_version 1.1; 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; } }
Save the file by pressing Ctrl + X and entering Y when prompted.
Give Nginx permissions to the cache directory:
sudo chown -R nginx:nginx /var/cache/nginx
Verify your Nginx configuration:
sudo nginx -t
If there are no errors, restart the Nginx server:
sudo systemctl restart nginx
Step 10 – Access Mattermost Server
Now that everything is set up, you can access your Mattermost server by opening the URL https://mattermost.example.com
in your browser. You will be greeted with the Mattermost signup page. Enter your account details, and you will be set as the system administrator.
To ensure security, we need to close port 8065 since we have configured Mattermost to be accessible via a public URL. Therefore, the open port poses a security risk. Run the following command to delete the temporary rule:
sudo ufwdelete allow 8065
Next, you will be taken to the team creation page. Click the “Create a team” button to create your first team.
You will be asked to set a public URL for the team. Choose a URL and click the “Finish” button to open the Mattermost dashboard.
Step 11 – Configure Mattermost Server
You can configure Mattermost using the config.json
file or the System Console from the dashboard. In this guide, we will use the System Console for simplicity.
Click the “Product Button” on the top left corner of the Mattermost dashboard and select the “System Console” option.
The System Console dashboard allows you to configure various settings for your Mattermost server. One essential configuration is email notifications. To enable email notifications, follow these steps:
- Visit System Console >> Site Configuration >> Notifications menu.
- Set “Enable Email Notifications” to “true”.
- Set “Notification Display Name” to “No-Reply”.
- Set “Notification From Address” to an appropriate email address, such as [email protected]
- Set “Support Email Address” to a support email address, such as [email protected]
To enable SMTP for email sending, go to System Console >> Environment >> SMTP menu and configure the following options:
- Set “SMTP Server” to your SMTP server address.
- Set “SMTP Server Port” to the appropriate port number.
- Enable SMTP authentication if required and provide the username and password.
- Set the “Connection Security” to the appropriate value (TLS or STARTTLS).
Click the “Test Connection” button to verify the SMTP settings.
Feel free to explore other available settings in the System Console to further customize your Mattermost server.
Remember to restart the Mattermost server in the terminal for the changes to take effect:
sudo systemctl restart mattermost
Conclusion
Congratulations! You have successfully installed and configured the Mattermost Team Messaging System on your Ubuntu 22.04 server. By hosting Mattermost on your own server, you have gained control over your communications and sensitive data. Mattermost provides a secure and feature-rich messaging platform, making it an excellent alternative to other professional platforms. If you have any questions or need further assistance, feel free to post them in the comments below.
This article was brought to you by Shape.host, a leading provider of Linux SSD VPS hosting services. With Shape.host, you can enjoy reliable and scalable cloud hosting solutions for your business.