Mattermost on AWS User Guide

Overview

This image runs Mattermost Team Edition as a single Go binary behind nginx, configured as a websocket-aware reverse proxy. PostgreSQL provides the database, bound to the loopback interface only. The Mattermost server listens on 127.0.0.1:8065 and is reached by customers through nginx on port 80 (and 443 once you add TLS).

A Mattermost System Administrator account and the PostgreSQL password are generated on the first boot of every deployed instance. Two instances launched from the same Amazon Machine Image never share passwords. The initial administrator password and the database password are written to /root/mattermost-credentials.txt with mode 0600 so that only the root user can read them.

The PostgreSQL data directory sits on its own EBS volume at /var/lib/postgresql, and Mattermost file storage (uploads and plugins) on a second volume at /opt/mattermost/data, each separate from the operating system disk and independently resizable.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will reach Mattermost on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Mattermost. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes approximately one to two minutes after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Mattermost Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=mattermost-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve Initial Credentials

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/mattermost-credentials.txt

You will see a plain text file containing the Mattermost URL, the administrator username (admin), the administrator password, and the PostgreSQL database name, user, and password. Copy these values somewhere secure (a password manager or encrypted vault). Do not commit them to source control.

From the same SSH session you can confirm the deployment is healthy. The system ping endpoint is open and returns JSON:

curl -fsS http://127.0.0.1/api/v4/system/ping

{"AndroidLatestVersion":"","AndroidMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}

A "status":"OK" response confirms the full stack - nginx, the Mattermost server and PostgreSQL - is serving.

Step 4: First Login

Open a web browser and navigate to http://<public-ip>/. Mattermost presents its sign-in page. Enter the username admin and the administrator password from /root/mattermost-credentials.txt, then select Log in.

The Mattermost Team Edition sign-in page, served on first boot with no manual setup.

The first boot service sets Mattermost's Site URL to the instance's own address automatically, so the site works immediately on its launch address. When you move Mattermost behind a custom domain or a load balancer, update the Site URL in the System Console (Step 7) or with the CLI.

Step 5: Create Your First Team and Channels

On first sign-in, create a team - a workspace that contains channels and members. Give it a name and a URL, then you land in the team's default Town Square channel. Create public or private channels for projects and topics from the + next to the channel list, and start direct messages from the Direct Messages section.

The Mattermost channels view: real-time messaging with channels, threads and direct messages.

Step 6: Connect Desktop and Mobile Apps

Mattermost has native desktop apps (Windows, macOS, Linux) and mobile apps (iOS, Android). Download them from https://mattermost.com/download/, point each app at your instance address, and sign in. The same REST API the apps use is served by this image - you can verify it is live and gated:

# Without a token the API returns 401
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/api/v4/users/me
# Logging in with the admin credentials returns 200
curl -s -o /dev/null -w '%{http_code}\n' -d '{"login_id":"admin","password":"<new-password>"}' http://127.0.0.1/api/v4/users/login

Step 7: The System Console

The System Console is the administration area for the whole server. Open it from the ⚙ settings menu, or browse to http://<public-ip>/admin_console. From here you manage users and teams, configure authentication, email, file storage and integrations, and review site statistics and server logs.

The System Console: Team Edition under the Mattermost MIT Compiled License.

User management in the System Console, showing the per-instance System Admin account generated on first boot.

Administration is also available from the command line with the Mattermost CLI in local mode:

sudo -u mattermost /opt/mattermost/bin/mmctl --local user list --all

Step 8: Configure Outbound Email

Mattermost needs to send mail for invitations, password resets and notifications. In the System Console open Environment then SMTP, and enter your provider's host, port, encryption and credentials. For reliable delivery on a cloud instance route mail through an SMTP provider such as Amazon SES, SendGrid, or Mailgun, then send a test email.

Step 9: Enable HTTPS with Let's Encrypt

For any production Mattermost deployment serve the site over HTTPS so session tokens and messages cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d mattermost.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

After certbot finishes, set the Site URL to the HTTPS address so Mattermost generates correct links:

sudo -u mattermost /opt/mattermost/bin/mmctl --local config set ServiceSettings.SiteURL https://<your-domain>
sudo systemctl restart mattermost

Step 10: Backups and Maintenance

Mattermost has two things that must be backed up together: the PostgreSQL database and the file storage directory /opt/mattermost/data (uploads and plugins).

sudo -u postgres pg_dump mattermost > <backup-dir>/mattermost-db-$(date +%F).sql
sudo tar -czf <backup-dir>/mattermost-data-$(date +%F).tgz -C /opt/mattermost data

Ship both artifacts to an Amazon S3 bucket or another object store. Because the database and file tiers are on their own EBS volumes, you can also take coordinated EBS snapshots. For kernel and package updates, Ubuntu's unattended-upgrades is enabled by default. To upgrade Mattermost itself, follow the upgrade guide at https://docs.mattermost.com/.

Step 11: Scaling Beyond a Single Instance

For larger deployments decouple Mattermost from the single instance pattern:

• Move PostgreSQL to Amazon RDS for PostgreSQL and update SqlSettings.DataSource in the System Console or config.json
• Move file storage to Amazon S3 under Environment then File Storage in the System Console
• Put the web tier behind an Application Load Balancer with sticky sessions and websocket support
• Serve static assets through Amazon CloudFront

Each of these is documented in the official Mattermost documentation at https://docs.mattermost.com/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general Mattermost administration questions consult the documentation at https://docs.mattermost.com/. Mattermost is a trademark of Mattermost, Inc.; use of the name here is nominative and does not imply affiliation or endorsement.