upstream-mattermost/docs/main/deployment-guide/server/deploy-containers.mdx

---
title: "Deploy Mattermost using Containers"
---
You can deploy Mattermost Server using container technologies for exploring functionality, testing, and development purposes, as it allows you to quickly set up a Mattermost instance without needing to manage the underlying infrastructure. This deployment method shouldn't be used in production environments as it doesn't support clustered deployments or High Availability (HA) configurations out-of-the-box.

<Warning>

- Mattermost server deployment using Docker is officially supported on Linux operating systems only.
- macOS and Windows Docker deployments are supported for testing and development purposes only.
- Docker is not ideal for High Availability (HA) because it lacks key features including automatic failover, shared storage, and load balancing. Docker also has challenges managing multiple nodes and recovering from failures. We recommend [deploying on Kubernetes](/deployment-guide/server/deploy-kubernetes) for HA for these features to ensure reliability.

</Warning>

If you don't have Docker installed, follow the instructions below based on your operating system. You'll need [Docker Engine](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) (release 1.28 or later).

<Tip>

**Need a FIPS / STIG-compliant image?** Mattermost publishes a FIPS-compliant, STIG-hardened variant of every container image. Swapping the image tag is the only change required — see [FIPS / STIG container builds](/deployment-guide/server/containers/fips-stig).

</Tip>

## Deploy Mattermost on Docker

This section provides a quick start guide for deploying Mattermost on Docker by leveraging [Docker Compose](https://docs.docker.com/compose/install/).

<Note>

- The deployment configuration results in two separate containers: a container for the database and a container for the application. An optional third container results when using NGINX for reverse proxy.
- Encountering issues with your Docker deployment? See the [Docker deployment troubleshooting](/deployment-guide/server/docker-troubleshooting) documentation for details.

</Note>

1.  In a terminal window, clone the repository and enter the directory.

    ``` sh
    git clone https://github.com/mattermost/docker
    cd docker
    ```

2.  Create your `.env` file by copying and adjusting the `env.example` file.

    ``` sh
    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.
    - We recommend configuring the [Support Email](/administration-guide/configure/site-configuration-settings#support-email-address) via `MM_SUPPORTSETTINGS_SUPPORTEMAIL`. This is the email address your users will contact when they need help.

    </Important>

3.  Create the required directories and set their permissions.

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

4.  *(Optional)* Configure TLS for NGINX. If you're not using the included NGINX reverse proxy, you can skip this step.

<Note>

**Resource limits:** If you're using a custom `docker-compose.yml` file that sets <code>pids_limit</code>, we recommend using `mem_limit` instead to constrain resources while allowing normal connection scaling. Low `pids_limit` values can prevent the container from creating enough processes or threads, which may lead to unstable behavior under load. The current default in `docker-compose.yml` is set to `mem_limit: 4G`.

</Note>

### Create a new certificate and key

``` sh
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.

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

### Use a pre-existing certificate and key

``` sh
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.

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

5.  Deploy Mattermost.

### Deploy without using the included NGINX

``` sh
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:

``` sh
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml down
```

### Deploy using the included NGINX

``` sh
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:

``` sh
docker compose -f docker-compose.yml -f docker-compose.nginx.yml down
```

6.  Create your first Mattermost system admin user, [invite more users](/end-user-guide/collaborate/manage-channel-members), and explore the Mattermost platform.

### Configure SSO with GitLab (optional)

To use SSO with GitLab with 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 the following line in your `.env` file, and ensure it points to your `pki_chain.pem` file:

``` sh
#GITLAB_PKI_CHAIN_PATH=<path_to_your_gitlab_pki>/pki_chain.pem
```

Then uncomment the following line in your `docker-compose.yml` file, and ensure it points to the same `pki_chain.pem` file:

``` sh
# - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro
```

### Upgrade from mattermost-docker

The [mattermost-docker](https://github.com/mattermost/mattermost-docker) GitHub repository is deprecated. Visit the [mattermost/docker](https://github.com/mattermost/docker) GitHub repository to access the official Docker deployment solution for Mattermost.

To migrate from an existing `mattermost/mattermost-prod-app` image, we recommend migrating to either `mattermost/mattermost-enterprise-edition` or `mattermost/mattermost-team-edition` images, which are the official images supported by Mattermost. These images support PostgreSQL v11+ databases, which we know has been a long-running challenge for the community, and you will not lose any features or functionality by moving to these new images.

For additional help or questions, please refer to [this issue](https://github.com/mattermost/mattermost-docker/issues/489).

### Install a different version of Mattermost

1.  Shut down your deployment.

2.  Run `git pull` to fetch any recent changes to the repository, paying attention to any potential `env.example` changes.

3.  Adjust the `MATTERMOST_IMAGE_TAG` in the `.env` file to point your desired [enterprise](https://hub.docker.com/r/mattermost/mattermost-enterprise-edition/tags?page=1&ordering=last_updated) or [team](https://hub.docker.com/r/mattermost/mattermost-team-edition/tags?page=1&ordering=last_updated) image version.

    <Important>

    **For production environments**, we recommend using specific version tags such as `MATTERMOST_IMAGE_TAG=release-10.5` rather than generic tags like `MATTERMOST_IMAGE_TAG=release-10`. Generic `release-x` tags are intended for development use only and do not automatically receive new patch releases within that major version. Using specific version tags ensures a more reproducible and deterministic environment for your production deployment.

    </Important>

4.  Redeploy Mattermost.

## Troubleshooting your Docker deployment

If deploying on an M1 Mac and encountering permission issues in the Docker container, redo the "create the required directories" step above and skip this command:

``` sh
sudo chown -R 2000:2000 ./volumes/app/mattermost
```

If having issues deploying on Docker generally, ensure the docker daemon is enabled and running:

``` sh
sudo systemctl enable --now docker
```

To remove all data and settings for your Mattermost deployment:

``` sh
sudo rm -rf ./volumes
```

### Troubleshooting PostgreSQL

For quick start deployments, you can change the Postgres username and/or password (recommended) in the `.env` file. If your database is managed externally, you'll need to change the password in your database management tool. Then, update the `.env` file with the new credentials.

### Troubleshooting TLS & NGINX

For an in-depth guide to configuring the TLS certificate and key for Nginx, please refer to [this document in the repository](https://github.com/mattermost/docker/blob/main/docs/issuing-letsencrypt-certificate.md).

## Trial Mattermost using Docker Preview

Looking for a way to evaluate Mattermost on a single local machine using Docker? We recommend using the [Mattermost Docker Preview Image](https://github.com/mattermost/mattermost-docker-preview) to install Mattermost in Preview Mode.

<Important>

- This local image is self-contained (i.e., it has an internal database and works out of the box). Dropping a container using this image removes data and configuration as expected. You can see the [configuration settings](/administration-guide/configure/configuration-settings) documentation to learn more about customizing your trial deployment.
- **Preview Mode** shouldn't be used in a production environment, as it uses a known password string, contains other non-production configuration settings, has email disabled, keeps no persistent data (all data lives inside the container), and doesn't support upgrades.
- If you are planning to use the calling functionality in **Preview Mode** on a non-local environment, you should ensure that the server is running on a secure (HTTPs) connection and that the [network requirements](/deployment-guide/calls/calls-rtcd-setup#network-requirements) to run calls are met.

</Important>

1.  Install [Docker](https://www.docker.com/get-started/).
2.  Once you have Docker, run the following command in a terminal window:

    ``` sh
    docker run --name mattermost-preview -d --publish 8065:8065 --publish 8443:8443 mattermost/mattermost-preview
    ```

3.  When Docker is done fetching the image, navigate to `http://localhost:8065/` in your browser to preview Mattermost.
4.  Select **Don't have an account** in the top right corner of the screen to create an account for your preview instance. If you don't see this option, ensure that the [Enable open server](/administration-guide/configure/authentication-configuration-settings#enable-open-server) configuration setting is enabled. This setting is disabled for self-hosted Mattermost deployments by default.
5.  Log in to your preview instance with your user credentials.

### Troubleshooting your preview deployment

The **Preview Mode** Docker instance for Mattermost is designed for product evaluation, and sets `SendEmailNotifications=false` so the product can function without enabling email. See the [Configuration Settings](/administration-guide/configure/configuration-settings) documentation to customize your deployment.

To update your Mattermost preview image and container, you must first stop and delete your existing **mattermost-preview** container by running the following commands:

``` sh
docker pull mattermost/mattermost-preview
docker stop mattermost-preview
docker rm mattermost-preview
```

Once the new image is pulled and the container is stopped and deleted you need to run the `docker run` command from above.

<Important>

On Linux, include `sudo` in front of all `docker` commands.

</Important>

To access a shell inside the container, run the following command:

``` sh
docker exec -ti mattermost-preview /bin/bash
```

<Note>

See [Docker deployment troubleshooting](/deployment-guide/server/docker-troubleshooting) for resolutions to common container issues, or [Deployment troubleshooting](/deployment-guide/server/troubleshooting) for issues that aren't specific to containers.

</Note>

## Secure your Mattermost deployment

Deploying Mattermost using Docker containers can be made secure with proper configurations for HTTPS and reverse proxying. This guide outlines the steps to set up TLS and an NGINX reverse proxy for your Mattermost deployment, ensuring secure communication between users and your server.

1.  Set Up an NGINX Container to serve as the reverse proxy. You can use NGINX either as a separate container or installed on the host machine.
2.  Bind Volumes for NGINX Configuration and TLS Certificates:

> - Bind Docker volumes for NGINX configuration files and TLS certificates to ensure persistent and secure storage of these assets.
> - Use permission restrictions on host directories where sensitive files such as TLS keys are stored.

3.  Create the NGINX Configuration File by designing a robust `nginx.conf` file to configure reverse proxying and HTTPS. Here's a basic example:

    ``` nginx
    server {
        listen 443 ssl;
        server_name your-domain.com;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;

        location / {
            proxy_pass http://mattermost:8065;
            proxy_set_header Host $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 https;
        }
    }
    ```

Verify the configuration with `nginx -t` before applying.

4.  Obtain TLS Certificates:

> - Use Let's Encrypt for free, automated certificates. Tools like Certbot can help automate the process.
> - Alternatively, purchase certificates from a trusted certificate authority (CA) and ensure proper setup of intermediate and root certificate chains.
>
> Keep private keys secure and avoid storing them directly inside Docker images.

5.  Connect Containers Using Docker Networking:

    > - Use Docker's networking features to isolate and link containers.
    >
    > - Create a custom Docker bridge network to ensure secure communication. For example:
    >
    >   ``` sh
    >   docker network create mattermost-network
    >   ```
    >
    > - Launch the Mattermost and NGINX containers on the same network:
    >
    >   ``` sh
    >   docker network connect mattermost-network mattermost
    >   docker network connect mattermost-network nginx
    >   ```

6.  Point your domain to the server IP address:

    Ensure your domain (e.g., your-domain.com) points to the public IP address of your server. If your IP is dynamic, consider setting up Dynamic DNS (DDNS) for seamless connectivity.

7.  After placing the certificates and updating the configuration, restart the NGINX container:

8.  Use logs (docker logs nginx) to troubleshoot and validate the container's operation.

9.  Verify HTTPS Access by visiting `https://your-domain.com` in a web browser to confirm Mattermost is running securely over HTTPS.

10. Use tools such as SSL Labs : [https://www.ssllabs.com/ssltest/](https://www.ssllabs.com/ssltest/) to validate the quality of your TLS setup.

11. Enable HTTP Strict Transport Security (HSTS) in your NGINX configuration to prevent downgrade attacks.

12. Use NGINX rate-limiting features to restrict abusive traffic, such as excessive requests:

Additionally, consider:

- Use Docker's security features such as Seccomp profiles and AppArmor to secure your container runtime.
- Avoid running containers with elevated privileges `--privileged` and utilize user namespaces.
- Always use trusted images (e.g., official NGINX and Mattermost images) to prevent exposure to vulnerabilities in third-party images.
- Update Mattermost, NGINX, and Docker to their latest versions regularly to ensure patches for known vulnerabilities are applied.
- Set up proper firewall rules to restrict unauthorized access and monitor traffic using tools like Fail2Ban or Wazuh.

By following these steps, your Mattermost deployment using Docker containers will be accessible securely over HTTPS with efficient proxying through NGINX. Implementing the additional security recommendations will further protect your environment against evolving threats.