Deploy Mattermost

Learn how to install, deploy, and scale Mattermost for teams and organizations of any size.

Deploy Mattermost for production use

When you’re ready to install Mattermost server for production use, you have four options: deploy using Kubernetes, deploy from a compressed tarball, deploy using a Ubuntu option called Omnibus, or deploy using Docker.

Learn how to install, deploy, and scale Mattermost for teams and organizations of any size using one of four options: deploy using Kubernetes, deploy from a compressed tarball, deploy using a Ubuntu option called Omnibus, or deploy using Docker.

Tip

See the configuration settings documentation to learn more about customizing your production deployment.
Encountering issues with your deployment? See the Deployment Troubleshooting documentation for details.

Mattermost bundles the components of a Mattermost deployment into a single installation, called Omnibus. Mattermost Omnibus currently supports Ubuntu’s bionic (18.04), focal (20.04) and jammy (22.04) distributions. The package bundles the free, unlicensed Mattermost Enterprise version of Mattermost, and leverages the apt package manager to install and update the platform components. A custom CLI and ansible recipes link the components together and configures them.

Minimum system requirements

Hardware: 2 vCPUs/cores with 4GB RAM (support for 1,000-2,000 users)
Database: MySQL v8+ or PostgreSQL v12+
Network ports required:
- Application ports 80/443, TLS, TCP Inbound
- Administrator Console port 8065, TLS, TCP Inbound
- SMTP port 10025, TCP/UDP Outbound

Deploy Omnibus

In a terminal window, run the following command to configure the repositories needed for a PostgreSQL database, configure an NGINX web server to act as a proxy, configure certbot to issue and renew the SSL certificate, and configure the Mattermost Omnibus repository so that you can run the install command.
```
curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash
```
Install the Omnibus package.
```
sudo apt install mattermost-omnibus -y
```

To issue the certificate, the installer requests a domain name and an email address from you. These are used to generate the certificate and deliver any related communications. After all the packages are installed, Omnibus runs ansible scripts that configure all the platform components and starts the server.
Note

If you encounter EXPKEYSIG, this indicates that the certificate is expired. To obtain a new certificate, run the following commands:
sudo apt-key remove 44774B28
sudo curl -o- https://deb.packages.mattermost.com/pubkey.gpg | sudo apt-key add -
sudo apt update

Open a browser and navigate to your Mattermost domain either by domain name (e.g. mymattermostserver.com), or by the server’s IP address if you’re not using a domain name.
Create your first Mattermost user, invite more users, and explore the Mattermost platform.

Note

We recommend installing and configuring Omnibus with SSL enabled; however, you can run the following command to disable SSL: sudo MMO_HTTPS=false apt install mattermost-omnibus.

Mattermost Omnibus is integrated with the apt package manager. When a new Mattermost version is released, run: sudo apt update && sudo apt upgrade to download and update your Mattermost instance.

Available on all plans

self-hosted deployments

These instructions outline how to install Mattermost Server on a 64-bit Linux host from a compressed tarball, and assume the IP address of the Mattermost server is 10.10.10.2.

Minimum system requirements

Hardware: 2 vCPUs/cores with 4GB RAM (support for 1,000-2,000 users)
Database: MySQL v8+ or PostgreSQL v12+
Network ports required:
- Application ports 80/443, TLS, TCP Inbound
- Administrator Console port 8065, TLS, TCP Inbound
- SMTP port 10025, TCP/UDP Outbound

Deploy Generic Linux

Install and configure a MySQL or PostgreSQL database. Refer to one of the guides below to deploy the database based on your operating system:
- Ubuntu
- Debian
- RHEL
Log in to the server that will host Mattermost Server and open a terminal window.
Download the latest version of the Mattermost Server. In the following command, replace X.X.X with the version that you want to download:
```
wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz
```
Extract the Mattermost Server files.
```
tar -xvzf mattermost*.gz
```
Move the extracted file to the /opt directory.
```
sudo mv mattermost /opt
```
Create the storage directory for files.
```
sudo mkdir /opt/mattermost/data
```

Note

The storage directory will contain all the files and images that your users post to Mattermost, so you need to make sure that the drive is large enough to hold the anticipated number of uploaded files and images.

Set up a system user and group called mattermost that will run this service, and set the ownership and permissions.

Create the Mattermost user and group.
sudo useradd --system --user-group mattermost
Set the user and group mattermost as the owner of the Mattermost files.
sudo chown -R mattermost:mattermost /opt/mattermost
Give write permissions to the mattermost group.
sudo chmod -R g+w /opt/mattermost

Set up the database driver in the file /opt/mattermost/config/config.json. Open the file in a text editor and make the following changes:

If you’re using PostgreSQL:

Set "DriverName" to "postgres" Set "DataSource" to the following value, replacing <mmuser-password> and <host-name-or-IP> with the appropriate values: "postgres://mmuser:<mmuser-password>@<host-name-or-IP>:5432/mattermost?sslmode=disable&connect_timeout=10",

If you’re using MySQL:

Set "DriverName" to "mysql" Set "DataSource" to the following value, replacing <mmuser-password> and <host-name-or-IP> with the appropriate values. Also make sure that the database name is mattermost instead of mattermost_test: "mmuser:<mmuser-password>@tcp(<host-name-or-IP>:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s"
Test the Mattermost server to make sure everything works.

Change to the Mattermost directory.
cd /opt/mattermost
Start the Mattermost server as the user mattermost.
sudo -u mattermost bin/mattermost
When the server starts, it shows some log information and the text Server is listening on :8065. You can stop the server by pressing Ctrl C on Windows or Linux, or ⌘ C on Mac, in the terminal window.

Set up Mattermost to use systemd for starting and stopping.

Create a systemd unit file.
sudo touch /lib/systemd/system/mattermost.service
Open the unit file as root in a text editor, and copy the following lines 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
Note

If you’re using MySQL, replace postgresql.service with mysql.service in two places in the [Unit] section.

If you’ve installed MySQL or PostgreSQL on a dedicated server, you need to remove the After=mysql.service and BindsTo=mysql.service or the After=postgresql.service and BindsTo=postgresql.service lines in the [Unit] section or the Mattermost service won’t start.
Make systemd load the new unit.
sudo systemctl daemon-reload
Check to make sure that the unit was loaded.
sudo systemctl status mattermost.service
You should see an output similar to the following:
mattermost.service - Mattermost
Loaded: loaded (/lib/systemd/system/mattermost.service; disabled; vendor preset: enabled)
Active: inactive (dead)
Start the service.
sudo systemctl start mattermost.service
Verify that Mattermost is running.
curl http://localhost:8065
You should see the HTML that’s returned by the Mattermost server. If a firewall is used, external requests to port 8065 may be blocked. Use sudo ufw allow 8065 to open port 8065.
Set Mattermost to start on machine start up.
sudo systemctl enable mattermost.service

Once you’re Mattermost server is up and running, create your first Mattermost user, invite more users, and explore the Mattermost platform.

You can install and deploy a production-ready Mattermost system on a Kubernetes cluster using the Mattermost Kubernetes Operator in practically any environment with less IT overhead and more automation.

You’ll need a Kubernetes cluster running version 1.16 or higher, Kubernetes CLI kubectl installed on local machine, and a basic understanding of Kubernetes concepts (such as deployments, pods) and actions (such as applying manifests, viewing pod logs). Running Mattermost in Kubernetes requires resources based on your total number of users. See the Mattermost Kubernetes Operator documentation to learn more about the minimum Kubernetes cluster resources Mattermost requires at different scales.

Tip

If you’re unsure about which environment you want to use for your Kubernetes cluster, we suggest using a managed service such as as Amazon EKS, Azure Kubernetes Service, Google Kubernetes Engine, or DigitalOcean Kubernetes.

Install the operators

Operators are installed using kubectl, and each operator is created in its own namespace. You can install and run multiple Mattermost installations in the same cluster using different namespaces.

Install NGINX ingress controller by following the instructions here.

Install the Mattermost Operator:

$ kubectl create ns mattermost-operator
$ kubectl apply -n mattermost-operator -f https://raw.githubusercontent.com/mattermost/mattermost-operator/master/docs/mattermost-operator/mattermost-operator.yaml

Tip

To install the operators using the Mattermost Operator Helm chart, follow the instructions here.

Deploy Mattermost

(Mattermost Enterprise only) Create a Mattermost license secret by opening a text editor and creating a secret manifest containing the Mattermost license. Replace [LICENSE_FILE_CONTENTS] below with the contents of your Mattermost license file. Save the file as mattermost-license-secret.yaml.

apiVersion: v1
kind: Secret
metadata:
  name: mattermost-license
type: Opaque
stringData:
  license: [LICENSE_FILE_CONTENTS]

Create an installation manifest file locally in a text editor by copying and pasting contenst from the Mattermost installation manifest, and adjusting fields for your configuration and environment.

apiVersion: installation.mattermost.com/v1beta1
kind: Mattermost
metadata:
  name: mm-example-full                         # Chose the desired name
spec:
  size: 5000users                               # Adjust to your requirements
  ingress:
    enabled: true
    host: example.mattermost-example.com        # Adjust to your domain
    annotations:
      kubernetes.io/ingress.class: nginx
  version: 6.0.1
  licenseSecret: ""                             # If you have created secret in step 1, put its name here
Save the file as mattermost-installation.yaml. While recommended file names are provided, your naming conventions may differ.

Some of the most commonly-used fields include:

Field

Description

Must Edit

metadata.name

The name of your Mattermost as it will be shown in Kubernetes. The shorter the better.

Yes

spec.size

The size of your installation. This can be ‘100users’, ‘1000users, ‘5000users’, ‘10000users’, or ‘25000users’.

Yes

spec.ingress.host

The DNS for your Mattermost installation.

Yes

spec.version

The Mattermost version.

No

spec.licenseSecret

The name of the Kubernetes secret containing your license (e.g. mattermost-license). Required for Enterprise deployments.

No

spec.mattermostEnv

List of custom environment variables for the Mattermost instance.

No

Additional fields are documented in the example.

If you have previous experience with Kubernetes Custom Resources

you can also check the Custom Resource Definition.

Create external database secret. (Skip if using MySQL and MinIO operators).

The database secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data:

Key

Description

Required

DB_CONNECTION_STRING

Connection string to the database.

Yes

MM_SQLSETTINGS_DATASOURCEREPLICAS

Connection string to read replicas of the database.

No

DB_CONNECTION_CHECK_URL

The URL used for checking that the database is accessible.

No

Example secret for AWS Aurora compatible with PostgreSQL:
apiVersion: v1
data:
  DB_CONNECTION_CHECK_URL: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK
  DB_CONNECTION_STRING: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK
  MM_SQLSETTINGS_DATASOURCEREPLICAS: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLXJvLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK
kind: Secret
metadata:
  name: my-postgres-connection
type: Opaque
Note

For PostgreSQL databases, the connection is checked with pg_isready so the DB_CONNECTION_CHECK_URL is the same as connection string.

For MySQL databases, the check is performed via HTTP call; therefore DB_CONNECTION_CHECK_URL should be an HTTP URL.

Create external filestore secret (Skip if using MySQL and MinIO operators).

The filestore secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data:

Key

Description

Required

accesskey

Filestore access key.

Yes

secretkey

Filestore secret key.

Yes

Example secret for AWS S3:
apiVersion: v1
data:
  accesskey: QUNDRVNTX0tFWQo=
  secretkey: U1VQRVJfU0VDUkVUX0tFWQo=
kind: Secret
metadata:
  name: my-s3-iam-access-key
type: Opaque

Adjust installation manifest (Skip if using MySQL and MinIO operators).

To instruct Mattermost Operator to use the external database, modify Mattermost manifest by adding the following fields:

spec:
...
  database:
    external:
      secret: my-postgres-connection

To instruct Mattermost Operator to use the external filestore, modify Mattermost manifest by adding the following fields:

spec:
...
  fileStore:
    external:
      url: s3.amazonaws.com
      bucket: my-s3-bucket
      secret: my-s3-iam-access-key

Additionally when using Amazon S3, set the MM_FILESETTINGS_AMAZONS3SSE and MM_FILESETTINGS_AMAZONS3SSL environment variables to true:

spec:
...
  mattermostEnv:
    ...
    - name: MM_FILESETTINGS_AMAZONS3SSE
      value: "true"
    - name: MM_FILESETTINGS_AMAZONS3SSL
      value: "true"

Example Mattermost manifest configured with both external databases and filestore:

apiVersion: installation.mattermost.com/v1beta1
kind: Mattermost
metadata:
  name: mm-example-external-db
spec:
  size: 5000users
  ingress:
    enabled: true
    host: example.mattermost-example.com
    annotations:
      kubernetes.io/ingress.class: nginx
  version: 6.0.1
  licenseSecret: ""
  database:
    external:
      secret: my-postgres-connection
  fileStore:
    external:
      url: s3.amazonaws.com
      bucket: my-s3-bucket
      secret: my-s3-iam-access-key
  mattermostEnv:
  - name: MM_FILESETTINGS_AMAZONS3SSE
    value: "true"
  - name: MM_FILESETTINGS_AMAZONS3SSL
    value: "true"

Apply the installation manifest file. Manifests are applied with kubectl. Before running the commands make sure you are connected to your Kubernetes cluster.

Create the Mattermost namespace:
$ kubectl create ns mattermost
(Mattermost Enterprise only) apply the license file by specifying the path to the file you created in step 1:
$ kubectl apply -n mattermost -f [PATH_TO_LICENCE_SECRET_MANIFEST]
Apply the installation file by specifying the path to the file you created in step 2:
$ kubectl apply -n mattermost -f [PATH_TO_MATTERMOST_MANIFEST]
The deployment process can be monitored in the Kubernetes user interface or in command line by running:
$ kubectl -n mattermost get mm -w
The installation should be deployed successfully, when the Custom Resource reaches the stable state.

Configure DNS and use Mattermost.

When the deployment is complete, obtain the hostname or IP address of your Mattermost deployment using the following command:
$ kubectl -n mattermost get ingress
Copy the resulting hostname or IP address from the ADDRESS column, open your browser, and connect to Mattermost.

Use your domain registration service to create a canonical name or IP address record for the ingress.host in your manifest, pointing to the address you just copied. For example, on AWS you would do this within a hosted zone in Route53.

Navigate to the ingress.host URL in your browser and use Mattermost.

If you just want to try it out on your local machine without configuring the domain, run:
$ kubectl -n mattermost port-forward svc/[YOUR_MATTERMOST_NAME] 8065:8065
Then navigate to http://localhost:8065.

You’ll need Docker Engine and Docker Compose (release 1.28 or later) Follow the steps in the Mattermost Docker Setup README or follow the steps below.

Encountering issues with your Docker deployment? See the Docker deployment troubleshooting documentation for details.

In a terminal window, clone the repository and enter the directory.
```
git clone https://github.com/mattermost/docker
cd docker
```
Create your .env file by copying and adjusting the env.example file.
```
cp env.example .env
```

Important

At a minimum, you must edit the DOMAIN value in the .env file to correspond to the domain for your Mattermost server.

Create the required directories and set their permissions.

mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
sudo chown -R 2000:2000 ./volumes/app/mattermost

Configure TLS for NGINX (optional). If you’re not using the included NGINX reverse proxy, you can skip this step.

If creating a new certificate and key:

bash scripts/issue-certificate.sh -d <YOUR_MM_DOMAIN> -o ${PWD}/certs

To include the certificate and key, uncomment the following lines in your .env file and ensure they point to the appropriate files.

#CERT_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/fullchain.pem
#KEY_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/privkey.pem

If using a pre-existing certificate and key:

mkdir -p ./volumes/web/cert
cp <PATH-TO-PRE-EXISTING-CERT>.pem ./volumes/web/cert/cert.pem
cp <PATH-TO-PRE-EXISTING-KEY>.pem ./volumes/web/cert/key-no-password.pem

To include the certificate and key, ensure the following lines in your .env file points to the appropriate files.

CERT_PATH=./volumes/web/cert/cert.pem
KEY_PATH=./volumes/web/cert/key-no-password.pem

Configure SSO with GitLab (optional). If you want to use SSO with GitLab, and you’re using a self-signed certificate, you have to add the PKI chain for your authority. This is required to avoid the Token request failed: certificate signed by unknown authority error.

To add the PKI chain, uncomment this line in your .env file, and ensure it points to your pki_chain.pem file:
```
#GITLAB_PKI_CHAIN_PATH=<path_to_your_gitlab_pki>/pki_chain.pem
```
Then uncomment this line in your docker-compose.yml file, and ensure it points to the same pki_chain.pem file:
```
# - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro
```
Deploy Mattermost.

Without using the included NGINX:
```
sudo docker-compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d
```
To access your new Mattermost deployment, navigate to http://<YOUR_MM_DOMAIN>:8065/ in your browser.

To shut down your deployment:
```
sudo docker-compose -f docker-compose.yml -f docker-compose.without-nginx.yml down
```
Using the included NGINX:
```
sudo docker-compose -f docker-compose.yml -f docker-compose.nginx.yml up -d
```
To access your new Mattermost deployment via HTTPS, navigate to https://<YOUR_MM_DOMAIN>/ in your browser.

To shut down your deployment:
```
sudo docker-compose -f docker-compose.yml -f docker-compose.nginx.yml down
```
Create your first Mattermost System Admin user, invite more users, and explore the Mattermost platform.

Prepare for your Mattermost deployment

These guides will help you prepare for your Mattermost deployment.

Preview Mattermost via Docker - Preview Mattermost instantly or deploy via Docker for production use.
Administrator tasks - Learn about the standard configurations and settings you’ll encounter.
Architecture - Learn the basics of user authentication, notifications, data management services, network connectivity, and high availability.
Implement Mattermost - Get a detailed breakdown of the technical requirements to deploy Mattermost for your team or organization.
Enterprise roll out checklist - Learn how to roll Mattermost out to thousands of users.
Welcome email template - Use our sample email template when you’re ready to invite users to your server.

Install guides

The Mattermost server and client apps can run on all of the most popular platforms. Here’s a list of the most popular installation methods.

Server installation

Desktop and Mobile App installation

These guides will get you up and running with Mattermost desktop and mobile apps in minutes.

Deployment guide

The deployment guide is for administrators who are ready to integrate Mattermost with their organization’s IT infrastructure.

Server deployment

Deployment overview - Learn the basics of the Mattermost user experience, communication protocols, network access, data storage, and deployment options.
Set up a socket-based Mattermost database - Connect your Mattermost server to your database service.
Image proxy - Setup and configure an image proxy to make loading images faster and more reliable and prevent pixel tracking.
Backup and disaster recovery - Implement data backups, disaster recovery, and high availability deployment.
Encryption options - Setup encryption for data in transit and at rest.
Configure transport encryption - Use transport encryption between Mattermost clusters and your proxy and database.
Bleve search - Use the Bleve search engine to provide Lucene-style full-text search.

Desktop and Mobile App deployment

Customize the Mattermost desktop and mobile apps to meet any deployment needs.

Desktop Apps

Desktop app deployment guide - Customize and distribute the Mattermost desktop app with pre-configured settings.
Desktop MSI installer and group policy installation guides (beta) - Use the Mattermost MSI installer and Group Policy definitions for Windows deployment.
Desktop app custom dictionaries - Create custom dictionaries for Mattermost spellcheck.
Desktop managed resources - Configure resource management for services running on the same domain as your Mattermost instance.

Mobile Apps

Using Mattermost’s pre-built mobile apps - Connect users to your Mattermost server with our prebuilt apps for Android and iOS.
Deploy Mattermost mobile apps - Learn the basics of how to customize and deploy Mattermost to the Enterprise.
Mobile push notifications - Set up mobile push notifications.
Building and distributing your own custom Mattermost mobile apps - Build custom mobile Mattermost apps.
Deploying mobile apps using an EMM provider - Deploy with Enterprise Mobile Management software to enforce security policies and enforce specific versions of the Mattermost mobile apps.
AppConfig for EMM solutions with Mattermost mobile apps - Learn how AppConfig provides an easy way to configure enterprise mobile applications.
Mobile VPN options - Learn how to use the Mattermost mobile apps with Mobile VPNs.
Mobile apps frequently asked questions
Client-side data storage frequently asked questions

Upgrade Mattermost

Stay up to date with the latest features and improvements.

Prepare to upgrade Mattermost - Learn how to prepare for a Mattermost upgrade.
Upgrade Mattermost Server - Learn the basics of upgrading your Mattermost server to the latest version.
Enterprise install and upgrade - Learn how to upgrade your Mattermost server to premium versions.
Install a license key - Learn how to add or change a Mattermost license key.
Release definitions - Get details on the Mattermost release schedule and the types of releases.
Important upgrade notes - Find version-specific upgrade considerations.
Release lifecycle - See critical release lifecycle dates.
Extended Support Release - Get information about releases that have extended release support.
Downgrade Mattermost Server - Find out how to roll back to older versions of Mattermost.
Version archive - Download binaries for every release.

Scale Mattermost

Scale and monitor your Mattermost deployment.

Scale for Enterprise - Scale Mattermost to tens of thousands of users and beyond.
High availability cluster - Maintain Mattermost service during outages and hardware failures with redundant infrastructure.
Elasticsearch - Enhance search performance with Elasticsearch.
Performance monitoring - Use Prometheus and Grafana to monitor the health and performance of your Mattermost cluster.
Mattermost performance alerting guide - Learn strategies and best practices for monitoring your Mattermost cluster.

Deploy Mattermost