How to Install Mattermost

Step 1: Prepare the Server

Start with a Linux server running Ubuntu 22.04 LTS or 24.04 LTS. Other supported distributions include Debian 12, RHEL 9 and Rocky Linux 9. The server should have a public IP address (or be accessible within your network) and SSH access configured.

Minimum hardware requirements depend on your team size. For teams up to 100 users, provision at least 2 CPU cores, 4 GB of RAM and 40 GB of SSD storage. For teams of 100 to 500 users, increase to 4 CPU cores, 8 GB of RAM and 80 GB of SSD storage. Mattermost is written in Go, which is efficient with CPU and memory, so these specifications provide comfortable headroom beyond the absolute minimums.

Update the system packages and install Docker Engine along with the Docker Compose plugin. On Ubuntu, add Docker's official APT repository, then install the docker-ce, docker-ce-cli, containerd.io and docker-compose-plugin packages. Verify the installation by running docker --version and docker compose version. Both commands should return version information without errors.

Create a dedicated user for running the Mattermost containers or add your existing user to the docker group. Running containers as root is technically possible but not recommended for production deployments.

Step 2: Clone the Mattermost Docker Repository

Mattermost maintains an official Docker deployment repository on GitHub at mattermost/docker. Clone this repository to your server to get the production-ready docker-compose configuration along with all necessary support files.

The repository contains the docker-compose.yml file that defines three services: the Mattermost application server, a PostgreSQL 15 database, and an Nginx reverse proxy. It also includes template configuration files for Nginx and environment variable defaults.

Copy the provided env.example file to .env in the same directory. This file contains all the configuration variables that control the deployment, including the domain name, database credentials, Mattermost version, and container resource limits. The .env file is excluded from version control by default, so your credentials remain private.

Step 3: Configure Environment Variables

Open the .env file and set the following key variables. The DOMAIN variable should match the fully qualified domain name you plan to use (for example, chat.yourcompany.com). This value is used by both the Nginx configuration and Let's Encrypt certificate provisioning.

Set POSTGRES_PASSWORD to a strong, randomly generated password. This password is used internally between the Mattermost application and the PostgreSQL container, so it does not need to be memorable. The POSTGRES_USER and POSTGRES_DB variables can remain at their defaults unless your organization has specific naming conventions.

The MATTERMOST_IMAGE variable controls which Mattermost edition and version to deploy. The default pulls the Team Edition, which is free and covers core messaging features. If you have an Enterprise Edition license, change this to the enterprise image tag. Set MATTERMOST_IMAGE_TAG to the specific version you want to deploy (for example, 11.8) or leave it as latest to always pull the most recent stable release.

Review the volume mount paths to ensure the data directories exist and have appropriate permissions. The default configuration stores PostgreSQL data, Mattermost configuration, logs, plugins and uploaded files in subdirectories relative to the docker-compose file. For production, consider placing data volumes on a separate disk or volume that is backed up independently from the OS disk.

Step 4: Start the Containers

With the environment configured, start all services by running docker compose up -d from the directory containing the docker-compose file. The -d flag runs the containers in detached mode so they continue running after you close the terminal session.

Docker will pull the Mattermost, PostgreSQL and Nginx images on the first run, which may take a few minutes depending on your network speed. After the images are downloaded, the containers start in sequence: PostgreSQL initializes the database first, then Mattermost connects and runs its schema migrations, and finally Nginx starts accepting HTTP connections.

Monitor the startup process by running docker compose logs -f and watching for the Mattermost server's "Server is listening" message, which confirms that the application has started successfully. If you see database connection errors, wait a few seconds and check again, as PostgreSQL may still be completing its initialization.

Verify that all three containers are running with docker compose ps. You should see the Mattermost, database and Nginx containers listed with a status of "Up". If any container has exited, check its logs with docker compose logs [service-name] to diagnose the issue.

Step 5: Set Up SSL and Domain

Before exposing Mattermost to users, configure SSL to encrypt all traffic. Create a DNS A record pointing your domain (for example, chat.yourcompany.com) to your server's public IP address. If the server has an IPv6 address, add an AAAA record as well.

The Mattermost Docker deployment includes an Nginx configuration that can be paired with Certbot for automatic Let's Encrypt certificate provisioning. Install Certbot on the host machine, then run it in standalone mode or webroot mode to obtain certificates for your domain. Update the Nginx configuration to reference the certificate and key files, then reload Nginx.

Alternatively, if you prefer automated certificate management within the Docker stack, replace the Nginx container with Caddy, which handles Let's Encrypt certificates automatically without additional configuration. Several community-maintained docker-compose variations use Caddy instead of Nginx for this reason.

Test the SSL configuration by accessing https://chat.yourcompany.com in a browser. Verify the certificate is valid, the connection is encrypted, and the Mattermost login page loads correctly. Check with an SSL testing tool like Qualys SSL Labs to confirm there are no configuration weaknesses.

Step 6: Complete Initial Setup and Configure SMTP

The first time you access Mattermost through the browser, a setup wizard prompts you to create the initial administrator account. Choose a strong password for this account, as it has full administrative privileges over the entire system. After creating the account, you will be taken to the main Mattermost interface.

Navigate to the System Console (accessible from the product menu in the top-left corner) to configure essential settings. Under Email Settings, configure SMTP to enable email notifications, password reset emails and invitation links. You will need the SMTP server address, port, authentication credentials and the "from" email address. Common SMTP providers include Amazon SES, Mailgun, Postmark, or your organization's existing mail server.

Under Site Configuration, set the Site URL to your full HTTPS URL (for example, https://chat.yourcompany.com). This setting is critical because Mattermost uses it to generate links in email notifications, WebSocket connections and API responses. An incorrect Site URL causes broken links and connectivity issues.

Configure push notifications so mobile app users receive alerts when they are mentioned or receive direct messages. Mattermost provides a hosted push notification service (HPNS) for Team Edition users, or you can run your own push notification proxy for complete data isolation. Enable the HPNS under the Push Notification Server settings in the System Console.

Finally, set up the initial channel structure. Create channels for each team or project, a general announcements channel, and any department-specific channels. Configure default channels that new users automatically join, and review the default notification preferences to ensure they match your organization's expectations.