Mattermost Installation for Team Communication

Mattermost is an open-source, self-hosted team communication and collaboration platform designed as an alternative to Slack. With features like messaging, video conferencing, file sharing, and integrations with popular tools, Mattermost enables secure team communication while maintaining complete data ownership. This guide covers the complete installation process, including PostgreSQL database setup, Nginx configuration, SSL encryption, and team configuration.

Table of Contents

Prerequisites

Before installation, ensure you have:

  • Ubuntu 20.04 LTS or later
  • Root or sudo access
  • A valid domain name
  • Minimum 4GB RAM (8GB recommended for production)
  • 20GB available disk space
  • Basic Linux administration knowledge

Update system packages:

sudo apt update && sudo apt upgrade -y

System Requirements

Verify system specifications for Mattermost:

Check system architecture:

uname -m
cat /etc/os-release

Verify available resources:

free -h
df -h

PostgreSQL Installation

Install PostgreSQL database server:

sudo apt install -y postgresql postgresql-contrib

Start and enable PostgreSQL:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Verify PostgreSQL status:

sudo systemctl status postgresql

Create Mattermost database:

sudo -u postgres psql << EOF
CREATE DATABASE mattermost;
CREATE USER mattermost WITH PASSWORD 'SecurePassword123!';
GRANT ALL PRIVILEGES ON DATABASE mattermost TO mattermost;
ALTER DATABASE mattermost OWNER TO mattermost;
\q
EOF

Test database connection:

psql -h localhost -U mattermost -d mattermost
\l
\q

Mattermost Installation

Create Mattermost installation directory:

sudo mkdir -p /opt/mattermost
cd /opt/mattermost

Download latest Mattermost release:

cd /tmp
wget https://releases.mattermost.com/mattermost-linux.tar.gz
tar -xzf mattermost-linux.tar.gz
sudo cp -r mattermost/* /opt/mattermost/

Create data directory:

sudo mkdir -p /opt/mattermost/data

Create Mattermost system user:

sudo useradd -r -s /bin/false -m -d /opt/mattermost mattermost

Set correct permissions:

sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R 755 /opt/mattermost
sudo chmod 700 /opt/mattermost/data

Nginx Configuration

Install Nginx:

sudo apt install -y nginx

Create Nginx configuration for Mattermost:

sudo nano /etc/nginx/sites-available/mattermost

Add configuration:

upstream mattermost {
    server localhost:8065 max_fails=5 fail_timeout=60s;
    keepalive 32;
}

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name example.com www.example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    client_max_body_size 100M;

    location / {
        proxy_pass http://mattermost;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_request_buffering off;
        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_read_timeout 600s;
        proxy_send_timeout 600s;
    }

    location /api/v4/users/websocket {
        proxy_pass http://mattermost;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Upgrade $http_upgrade;
        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_read_timeout 6h;
        proxy_send_timeout 6h;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Start Nginx:

sudo systemctl start nginx
sudo systemctl enable nginx

SSL Certificate Setup

Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

Obtain SSL certificate:

sudo certbot certonly --standalone -d example.com -d www.example.com

The Nginx configuration already references these certificates. Verify certificate installation:

sudo openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates

Set up automatic renewal:

sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer

Initial Configuration

Edit Mattermost configuration file:

sudo nano /opt/mattermost/config/config.json

Update database settings:

"SqlSettings": {
    "DriverName": "postgres",
    "DataSource": "postgres://mattermost:SecurePassword123!@localhost:5432/mattermost?sslmode=disable&connect_timeout=10",
    "MaxIdleConns": 20,
    "MaxOpenConns": 300,
    "Trace": false,
    "AtRestEncryptKey": "generated-key-here",
    "QueryTimeout": 30
}

Update service settings:

"ServiceSettings": {
    "SiteURL": "https://example.com",
    "WebsocketURL": "wss://example.com",
    "LicenseFileLocation": "",
    "ListenAddress": ":8065",
    "ConnectionSecurity": "",
    "TLSCertFile": "",
    "TLSKeyFile": "",
    "UseSSL": false,
    "Forward80To443": false
}

Create systemd service file:

sudo nano /etc/systemd/system/mattermost.service

Add:

[Unit]
Description=Mattermost
After=network.target postgresql.service
BindsTo=postgresql.service

[Service]
Type=simple
ExecStart=/opt/mattermost/bin/mattermost
TimeoutStartSec=3600s
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost
LimitNOFILE=49152

[Install]
WantedBy=multi-user.target

Enable and start Mattermost:

sudo systemctl daemon-reload
sudo systemctl enable mattermost
sudo systemctl start mattermost

Verify Mattermost is running:

sudo systemctl status mattermost

Monitor logs:

sudo journalctl -u mattermost -f

Initial Configuration

Access Mattermost web interface:

Navigate to https://example.com and complete the setup wizard:

  1. Create the system admin account
  2. Configure workspace settings
  3. Set the team name and display name
  4. Verify email configuration

User and Team Management

Create additional users through the admin panel:

  1. System Console → User Management → Users
  2. Click "Invite User" to add new team members
  3. Configure user roles (Admin, Team Admin, User)

Create additional teams:

  1. Workspace → Create a Team
  2. Set team name, URL, and description
  3. Configure team privacy settings

Configure team channels:

  1. Create channels for different topics
  2. Configure channel privacy (Public/Private)
  3. Invite team members to relevant channels

Integrations Setup

Configure SMTP for email notifications:

  1. System Console → Environment → SMTP
  2. Set SMTP server details
  3. Configure sender email and password
  4. Test email configuration

Enable OAuth authentication:

  1. System Console → Authentication → OAuth 2.0
  2. Configure Google, GitHub, or LDAP authentication

Install slash commands for automation:

  1. System Console → Integrations → Slash Commands
  2. Create custom commands for team workflows

Enable incoming webhooks:

  1. System Console → Integrations → Incoming Webhooks
  2. Create webhooks for external service integration

Backup and Updates

Create backup script:

sudo nano /usr/local/bin/mattermost-backup.sh

Add:

#!/bin/bash

BACKUP_DIR="/backups/mattermost"
MATTERMOST_DIR="/opt/mattermost"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Stop Mattermost
sudo systemctl stop mattermost

# Database backup
pg_dump -U mattermost mattermost | gzip > "$BACKUP_DIR/mattermost-db-$DATE.sql.gz"

# Files backup
tar -czf "$BACKUP_DIR/mattermost-config-$DATE.tar.gz" "$MATTERMOST_DIR/config"
tar -czf "$BACKUP_DIR/mattermost-data-$DATE.tar.gz" "$MATTERMOST_DIR/data"

# Start Mattermost
sudo systemctl start mattermost

# Keep only 30 days of backups
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completed: $DATE"

Make executable:

sudo chmod +x /usr/local/bin/mattermost-backup.sh

Schedule daily backups:

sudo crontab -e

Add:

0 2 * * * /usr/local/bin/mattermost-backup.sh >> /var/log/mattermost-backup.log 2>&1

Update Mattermost:

sudo systemctl stop mattermost
cd /opt/mattermost
wget https://releases.mattermost.com/mattermost-linux.tar.gz
tar -xzf mattermost-linux.tar.gz
sudo chown -R mattermost:mattermost /opt/mattermost
sudo systemctl start mattermost

Troubleshooting

Check Mattermost status:

sudo systemctl status mattermost

View error logs:

sudo journalctl -u mattermost -n 50

Verify database connectivity:

psql -h localhost -U mattermost -d mattermost
\dt
\q

Check Nginx configuration:

sudo nginx -t
sudo systemctl status nginx

Restart services if needed:

sudo systemctl restart mattermost
sudo systemctl restart nginx

Conclusion

Mattermost is now fully installed and configured as a team communication platform. With PostgreSQL database, Nginx reverse proxy, SSL encryption, and proper integrations, you have a secure, self-hosted alternative to commercial messaging platforms. Regular backups and updates ensure system reliability and security. Configure teams, channels, and integrations to create a productive team workspace.