How to Deploy Mattermost – An Open-Source Slack Alternative

Mattermost is an open-source messaging and collaboration platform that enables teams to communicate through real-time messaging, voice calls, and screen sharing. It is an alternative to platforms such as Slack, with support for file sharing, notifications, webhooks, and bot integrations.

This article explains how to deploy Mattermost on an Ubuntu server and configure it with a domain name. It covers integration with a Vultr Managed Database for PostgreSQL for high availability, Nginx as a reverse proxy with TLS certificates, Postfix for email notifications, and Vultr Object Storage for file storage.

Prerequisites

Before you begin:

• Have access to a Ubuntu 22.04 server with at least 4 GB of RAM as a non-root user with sudo privileges.
• Deploy a Vultr Managed Database for PostgreSQL to use with Mattermost.
• Create a Vultr Object Storage subscription and a bucket to store your Mattermost files. For example, mattermost-data.
• Create a DNS A record pointing to the server IP address. For example, mattermost.example.com.

Set Up the Mattermost Database

Mattermost stores user accounts, application data, and runtime configurations in a PostgreSQL database. Using a Vultr Managed Database offloads storage and backups from your server and provides automatic failover.

1. Install the PostgreSQL client package on your server.

   CONSOLE

   Copy

   $ sudo apt install postgresql-client

   Explain Code

   Powered by Vultr AgentBeta

2. Connect to your Vultr Managed Database for PostgreSQL cluster using the psql utility. Replace DB_HOST with your cluster hostname and DB_PORT with the connection port found in the Vultr Console.

   CONSOLE

   Copy

   $ psql -h DB_HOST -U vultradmin -p DB_PORT -d defaultdb

   Explain Code

   Powered by Vultr AgentBeta

   Enter your Vultr Managed Database password when prompted.

3. Create a new database for Mattermost. For example, mattermostdb.

   SQL

   Copy

   defaultdb=> CREATE DATABASE mattermostdb;

   Explain Code

   Powered by Vultr AgentBeta

4. Create a new PostgreSQL user role for the database. For example, mmadmin.

   SQL

   Copy

   defaultdb=> CREATE USER mmadmin WITH PASSWORD 'your-password';

   Explain Code

   Powered by Vultr AgentBeta

5. Grant the user full privileges on the Mattermost database.

   SQL

   Copy

   defaultdb=> GRANT ALL PRIVILEGES ON DATABASE mattermostdb to mmadmin;

   Explain Code

   Powered by Vultr AgentBeta

6. Grant the user access to all objects in the public schema.

   SQL

   Copy

   defaultdb=> GRANT USAGE, CREATE ON SCHEMA PUBLIC TO mmadmin;

   Explain Code

   Powered by Vultr AgentBeta

7. Transfer ownership of the mattermostdb database to the new user.

   SQL

   Copy

   defaultdb=> ALTER DATABASE mattermostdb OWNER TO mmadmin;

   Explain Code

   Powered by Vultr AgentBeta

8. Exit the PostgreSQL console.

   SQL

   Copy

   defaultdb=> \q

   Explain Code

   Powered by Vultr AgentBeta

9. Connect to the cluster using the Mattermost database and user. Replace DB_HOST and DB_PORT with your cluster connection details.

   CONSOLE

   Copy

   $ psql -h DB_HOST -U mmadmin -p DB_PORT -d mattermostdb

   Explain Code

   Powered by Vultr AgentBeta

   Enter the mmadmin password when prompted.

10. List all databases to verify that mattermostdb appears with mmadmin as the owner.

    SQL

    Copy

    mattermostdb=> \l

    Explain Code

    Powered by Vultr AgentBeta

    Verify that mattermostdb appears in the list with mmadmin as the owner.

                                      List of databases
        Name      |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges
    ------------+----------+----------+-------------+-------------+-----------------------
     _dodb        | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =T/postgres          +
                  |          |          |             |             | postgres=CTc/postgres
     defaultdb    | vultradmin  | UTF8  | en_US.UTF-8 | en_US.UTF-8 |
     mattermostdb | mmadmin  | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =Tc/mmadmin          +
                  |          |          |             |             | mmadmin=CTc/mmadmin
     template0    | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
                  |          |          |             |             | postgres=CTc/postgres
     template1    | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
                  |          |          |             |             | postgres=CTc/postgres
    (5 rows)

11. Exit the PostgreSQL console.

    SQL

    Copy

    mattermostdb=> \q

    Explain Code

    Powered by Vultr AgentBeta

Install Mattermost

Mattermost distributes packages through its own apt repository. Adding the repository GPG key and running the setup script imports all repository metadata and ensures package authenticity.

1. Add the Mattermost GPG public key to the server keyring.

   CONSOLE

   Copy

   $ curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null

   Explain Code

   Powered by Vultr AgentBeta

2. Download and run the Mattermost repository setup script.

   CONSOLE

   Copy

   $ curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -s mattermost

   Explain Code

   Powered by Vultr AgentBeta

   The script imports the Mattermost repository information on your server.

3. Update the server package index.

   CONSOLE

   Copy

   $ sudo apt update

   Explain Code

   Powered by Vultr AgentBeta

4. Install Mattermost.

   CONSOLE

   Copy

   $ sudo apt install mattermost -y

   Explain Code

   Powered by Vultr AgentBeta

5. Check the Mattermost service status to verify that the package is installed.

   CONSOLE

   Copy

   $ sudo systemctl status mattermost

   Explain Code

   Powered by Vultr AgentBeta

   The service is installed but not running. The next section configures the database connection and domain before the service starts.

Configure Mattermost

Mattermost creates the /opt/mattermost directory on your server containing the full application and configuration files. The config/config.json file within that directory controls the database connection, site URL, and all other runtime settings.

1. Navigate to the Mattermost configuration directory.

   CONSOLE

   Copy

   $ cd /opt/mattermost/config/

   Explain Code

   Powered by Vultr AgentBeta

2. Copy the default configuration file and rename it to config.json.

   CONSOLE

   Copy

   $ cp config.defaults.json config.json

   Explain Code

   Powered by Vultr AgentBeta

3. Transfer ownership of config.json to the Mattermost system user.

   CONSOLE

   Copy

   $ sudo chown mattermost:mattermost config.json

   Explain Code

   Powered by Vultr AgentBeta

4. Set the file permissions to 600 to prevent other system users and processes from reading the file.

   CONSOLE

   Copy

   $ sudo chmod 600 config.json

   Explain Code

   Powered by Vultr AgentBeta

5. List the directory contents to verify the permission changes.

   CONSOLE

   Copy

   $ ls -l

   Explain Code

   Powered by Vultr AgentBeta

   The rw------- permissions on config.json confirm that only the Mattermost user can read or write the file.

6. Open config.json in a text editor.

   CONSOLE

   Copy

   $ sudo nano config.json

   Explain Code

   Powered by Vultr AgentBeta

7. Find the ServiceSettings section and set SiteURL to your domain. Replace mattermost.example.com with your actual domain.

   JSON

   Copy

   "SiteURL": "https://mattermost.example.com",

   Explain Code

   Powered by Vultr AgentBeta

8. Find the SqlSettings section and replace the DataSource value with your Vultr Managed Database connection string. Replace mmadmin, your-password, DB_HOST, DB_PORT, and mattermostdb with your actual values. Also change sslmode from disable to require.

   JSON

   Copy

   "DataSource": "postgres://mmadmin:your-password@DB_HOST:DB_PORT/mattermostdb?sslmode=require&connect_timeout=10&binary_parameters=yes",

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

9. Start the Mattermost service to validate and apply the configuration.

   CONSOLE

   Copy

   $ sudo systemctl start mattermost

   Explain Code

   Powered by Vultr AgentBeta

   Wait at least 5 minutes for Mattermost to apply all configurations and write the initial data to the PostgreSQL database. If the service fails to start, check the logs to identify the error.

   CONSOLE

   Copy

   $ sudo tail -n 20 /var/log/syslog

   Explain Code

   Powered by Vultr AgentBeta

10. Check the Mattermost service status to verify that it is running.

    CONSOLE

    Copy

    $ sudo systemctl status mattermost

    Explain Code

    Powered by Vultr AgentBeta

    Verify that the output shows Active: active (running).

Set Up Nginx as a Reverse Proxy

Mattermost listens on port 8065 by default and is not directly exposed to the internet. Nginx acts as a reverse proxy, accepting public connections on ports 80 and 443 and forwarding them to the Mattermost backend.

1. Update the server package index.

   CONSOLE

   Copy

   $ sudo apt update

   Explain Code

   Powered by Vultr AgentBeta

2. Install Nginx.

   CONSOLE

   Copy

   $ sudo apt install nginx -y

   Explain Code

   Powered by Vultr AgentBeta

3. Remove the default Nginx configuration to avoid conflicts on port 80.

   CONSOLE

   Copy

   $ sudo rm /etc/nginx/sites-enabled/default

   Explain Code

   Powered by Vultr AgentBeta

4. Create a new Nginx configuration file for Mattermost. Replace mattermost.example.com with your domain.

   CONSOLE

   Copy

   $ sudo nano /etc/nginx/sites-available/mattermost.example.com

   Explain Code

   Powered by Vultr AgentBeta

5. Add the following configuration, replacing mattermost.example.com with your actual domain.

   INI

   Copy

   upstream mattermost {
      server 127.0.0.1:8065;
      keepalive 32;
   }
   
   server {
     listen 80 default_server;
     server_name   mattermost.example.com;
     return 301 https://$server_name$request_uri;
   }
   
   server {
      listen 443 ssl http2;
      listen [::]:443 ssl http2;
      server_name   mattermost.example.com;
   
      http2_push_preload on;
   
      ssl_certificate /etc/letsencrypt/live/mattermost.example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/mattermost.example.com/privkey.pem;
      ssl_session_timeout 1d;
   
      ssl_protocols TLSv1.2 TLSv1.3;
   
      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;
      add_header Strict-Transport-Security max-age=15768000;
      ssl_stapling on;
      ssl_stapling_verify on;
   
      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 60s;
          send_timeout 300s;
          lingering_timeout 5s;
          proxy_connect_timeout 90s;
          proxy_send_timeout 300s;
          proxy_read_timeout 90s;
          proxy_http_version 1.1;
          proxy_pass http://mattermost;
      }
   
      location / {
          client_max_body_size 100M;
          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_http_version 1.1;
          proxy_pass http://mattermost;
      }
   }
   
   map $ssl_early_data $tls1_3_early_data {
     "~." $ssl_early_data;
     default "";
   }

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   The configuration redirects all HTTP connections to HTTPS and forwards both standard requests and WebSocket connections to Mattermost on port 8065.

6. Link the configuration file to the sites-enabled directory. Replace mattermost.example.com with your actual domain name.

   CONSOLE

   Copy

   $ sudo ln -s /etc/nginx/sites-available/mattermost.example.com /etc/nginx/sites-enabled/

   Explain Code

   Powered by Vultr AgentBeta

   Do not restart Nginx yet. TLS certificates must exist at the paths referenced in the configuration before Nginx can start without errors.

Secure the Mattermost Server

Ubuntu's Uncomplicated Firewall (UFW) restricts incoming connections by default. Open ports 80 and 443 to allow Let's Encrypt domain validation and HTTPS access, then generate TLS certificates for your domain.

1. Allow HTTP traffic on port 80 for Let's Encrypt domain validation.

   CONSOLE

   Copy

   $ sudo ufw allow 80 comment 'mattermost http'

   Explain Code

   Powered by Vultr AgentBeta

2. Allow HTTPS traffic on port 443 for secure client access.

   CONSOLE

   Copy

   $ sudo ufw allow 443 comment 'mattermost https'

   Explain Code

   Powered by Vultr AgentBeta

3. Reload UFW to apply the changes.

   CONSOLE

   Copy

   $ sudo ufw reload

   Explain Code

   Powered by Vultr AgentBeta

4. Check the firewall rules to verify that ports 80 and 443 are open.

   CONSOLE

   Copy

   $ sudo ufw status

   Explain Code

   Powered by Vultr AgentBeta

Generate TLS Certificates

1. Install the Certbot plugin for Nginx.

   CONSOLE

   Copy

   $ sudo apt install python3-certbot-nginx -y

   Explain Code

   Powered by Vultr AgentBeta

2. Generate TLS certificates for your domain using the certonly option to avoid Certbot modifying the Nginx configuration. Replace mattermost.example.com with your actual domain.

   CONSOLE

   Copy

   $ sudo certbot --standalone certonly -d mattermost.example.com --agree-tos

   Explain Code

   Powered by Vultr AgentBeta

   Enter your email address when prompted. Verify that the output confirms that the certificate files are saved at /etc/letsencrypt/live/mattermost.example.com/.

3. Test the Nginx configuration for syntax errors.

   CONSOLE

   Copy

   $ sudo nginx -t

   Explain Code

   Powered by Vultr AgentBeta

   Expected output:

   nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
   nginx: configuration file /etc/nginx/nginx.conf test is successful

4. Restart Nginx to apply the Mattermost configuration.

   CONSOLE

   Copy

   $ sudo systemctl restart nginx

   Explain Code

   Powered by Vultr AgentBeta

Access Mattermost

Mattermost displays a setup wizard on first access to create the administrator account and configure the workspace.

1. Open a web browser and navigate to your Mattermost domain.

   https://mattermost.example.com

   Verify that the Mattermost setup interface loads in your browser.

   

2. Click View in Browser to access the account setup options.

3. Enter your email address in the Email address field within the Create your account form.

4. Enter your administrator username in the Choose a Username field, then enter a strong password.

   

5. Click Create Account to create the administrator account.

6. Enter your workspace name in the Organization name field.

7. Select the external tools to activate in your Mattermost workspace and click Continue to save the selection. For example, select GitHub and Zoom.

   

8. Click Copy Link to copy and share your Mattermost invite link with your target users.

9. Click Finish setup to apply the configuration and open the Mattermost workspace.

10. Click Browse or Create Channels next to your Mattermost team name to set up a new channel.

    

11. Select Create new channel from the list of options.

12. Enter a channel name and set your visibility options. For example, enter mynewteam and select Public Channel to allow all workspace users to access the channel.

    

13. Enter a channel description and click Create channel.

14. Verify that the channel appears in the Channels list.

15. Enter a sample message in the channel to verify that the server is working correctly. For example, enter Hello World! This is a new Mattermost server and press Enter to send the message.

16. Verify that the message appears in the channel.

    

17. Open the main Mattermost menu next to Channels on the top navigation bar and select System Console to open the administrator console. Alternatively, navigate to /admin_console on your domain.

    https://mattermost.example.com/admin_console

    Verify that the Mattermost administrator console loads and displays the edition and license version installed on your server.

    

18. Find the USER MANAGEMENT section in the main navigation menu and click Users to view the list of workspace users.

    

19. Verify the user list and click the Actions menu to modify user roles.

20. Click Save to apply your changes.

21. Find the AUTHENTICATION section in the main navigation menu and click Signup to configure how users register.

22. Enter a comma-separated list of domain names in the Restrict new system and team members…. field to limit registration to specific email domains. For example, enter example.com,example.net.

    

23. Set Enable Open Server to true to allow new users with matching email domains to create accounts. Keep it set to false to disable self-registration and accept only invited users.

24. Click Save to apply the workspace configuration.

Enable Email Notifications

Mattermost sends notifications through an SMTP server. A Preview Mode: Email notifications have not been configured. alert displays in the interface when email is not configured. These steps install and configure Postfix as a send-only SMTP server for outgoing notifications.

1. Update the server package index.

   CONSOLE

   Copy

   $ sudo apt update

   Explain Code

   Powered by Vultr AgentBeta

2. Set the server hostname to your Mattermost domain. Replace mattermost.example.com with your actual domain.

   CONSOLE

   Copy

   $ sudo hostnamectl set-hostname mattermost.example.com

   Explain Code

   Powered by Vultr AgentBeta

3. Install the Postfix mailutils package.

   CONSOLE

   Copy

   $ sudo apt install mailutils -y

   Explain Code

   Powered by Vultr AgentBeta

   When prompted, select Internet Site and enter your domain as the system mail name.

4. Back up the original Postfix configuration file.

   CONSOLE

   Copy

   $ sudo cp /etc/postfix/main.cf /etc/postfix/main.ORIG

   Explain Code

   Powered by Vultr AgentBeta

5. Open the Postfix configuration file.

   CONSOLE

   Copy

   $ sudo nano /etc/postfix/main.cf

   Explain Code

   Powered by Vultr AgentBeta

6. Find the inet_interfaces directive and change its value from all to loopback-only.

   INI

   Copy

   inet_interfaces = loopback-only

   Explain Code

   Powered by Vultr AgentBeta

7. Find the mydestination directive and replace its value with the following.

   INI

   Copy

   mydestination = localhost.$mydomain,localhost,$myhostname

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

8. Restart Postfix to apply the configuration changes.

   CONSOLE

   Copy

   $ sudo systemctl restart postfix

   Explain Code

   Powered by Vultr AgentBeta

9. Send a test email to verify that Postfix is working. Replace johndoe@example.com with your email address.

   CONSOLE

   Copy

   $ echo "The Mattermost SMTP Server is ready to use" | mail -s "Hello from the Mattermost Server" johndoe@example.com

   Explain Code

   Powered by Vultr AgentBeta

10. Check the server logs to verify that the email was sent.

    CONSOLE

    Copy

    $ sudo tail -n 10 /var/log/syslog

    Explain Code

    Powered by Vultr AgentBeta

    Output:

    mattermost postfix/smtp[3869]: 0316A1FEBED: to=<johndoe@example.com>, relay=mail.example.com[192.0.2.200]:25, delay=2, delays=0/0/1/1, dsn=2.0.0, status=sent (250 OK id=1s99jD-005ocG-6w)

11. Check your inbox to verify that an email from server-username@your-mattermostdomain arrived. Emails sent to domains such as gmail.com may bounce due to missing MX and SPF DNS records on your domain.

    

Configure Mattermost to Use Postfix

1. Open the Mattermost administrator console.

   https://mattermost.example.com/admin_console

2. Find the ENVIRONMENT section in the main navigation menu and click SMTP to modify the email configuration.

   

3. Keep localhost as the SMTP Server value.

4. Replace the default value 10025 with 25 in the SMTP Server Port field.

5. Set Skip Server Certificate Verification to true to disable verification of the Postfix certificate.

6. Click Save to apply the SMTP configuration.

7. Click Test Connection to validate the SMTP connection. Verify that a No errors were reported while sending an email. Please check your inbox to make sure. message appears.

   

Enable Vultr Object Storage

By default, Mattermost stores file and image attachments in /opt/mattermost/data. Vultr Object Storage provides an S3-compatible endpoint that Mattermost can use instead, keeping attachments off the server disk.

1. Open the Mattermost administrator console.

   https://mattermost.example.com/admin_console

2. Find the ENVIRONMENT section in the main navigation menu and click File Storage.

3. Click the File Storage System dropdown and select Amazon S3.

   

4. Enter your Vultr Object Storage bucket name in the Amazon S3 Bucket field.

5. Leave the Amazon S3 Path Prefix and Amazon S3 Region fields empty.

6. Enter your Vultr Object Storage access key in the Amazon S3 Access Key ID field.

7. Enter your Vultr Object Storage hostname in the Amazon S3 Endpoint field.

   

8. Enter your Vultr Object Storage secret key in the Amazon S3 Secret Access Key field.

9. Keep Enable Secure Amazon S3 Connections set to true.

10. Click Save to apply the file storage configuration.

11. Click Test Connection to validate the credentials. Verify that a Connection was successful message appears.

    

    

Connect Client Applications

Mattermost provides client applications for Android, iOS, and desktop. Each client connects to your self-hosted server using the server URL and your workspace credentials.

1. Download and install the Mattermost application for your device. For example, Mattermost for Android.

2. Open the Mattermost application on your device.

3. Click Get Started.

   

4. Enter your Mattermost domain URL in the Server URL field.

5. Enter a display name in the Server display name field to identify your Mattermost workspace on the device.

   

6. Verify that a Server URL is valid. Server version: prompt appears below the URL field and click Connect.

7. Enter your workspace email and password to log in.

   

8. To create a new user account, click Don't have an account to access the signup form. When the account is created, open your invite link in a browser and log in to join a Mattermost channel.

9. Verify that the client application can access all enabled channels on the server.

   

Conclusion

You have deployed Mattermost on an Ubuntu server with a managed PostgreSQL database, Nginx reverse proxy with TLS, Postfix for email notifications, and Vultr Object Storage for file attachments. For more information, visit the Mattermost documentation.