Install Mattermost via Docker#

plans-img Available on all plans

deployment-img self-hosted deployments

Install Docker#

If you don’t have Docker installed, follow the instructions below based on your operating system:

Install Docker for Mac.

Install Docker for Windows.

Follow the Install Docker Engine on Ubuntu documentation, or you can use the Docker package from the Ubuntu repositories:

sudo apt update
sudo apt install docker.io
sudo systemctl start docker

Follow the Install Docker Engine on Fedora documentation, or you can use the Moby package (Moby is the FOSS upstream project to Docker) from the Fedora repositories:

sudo dnf install moby-engine
sudo systemctl start docker

Preview Mattermost using Docker#

You can install Mattermost server in Preview Mode using the Mattermost Docker Preview Image image to explore Mattermost product functionality on a single local machine.

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 documentation to learn more about customizing your preview deployment.

However, 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.

  1. Install Docker.

  2. Once you have Docker, run the following command in a terminal window:

docker run --name mattermost-preview -d --publish 8065:8065 mattermost/mattermost-preview

  1. When Docker is done fetching the image, navigate to http://localhost:8065/ in your browser to preview Mattermost.

  2. 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 configuration setting is enabled. This setting is disabled for self-hosted Mattermost deployments by default.

  3. 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 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:

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.

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

docker exec -ti mattermost-preview /bin/bash

Deploy Mattermost on Docker for production use#

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.

Important

  • The production configuration results in two separate containers: one for the database and one 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 documentation for details.

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

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

  2. 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.

  1. 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

  2. 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

  3. 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

  4. 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

  5. Create your first Mattermost System Admin user, invite more users, and explore the Mattermost platform.

Upgrade from mattermost-docker#

The mattermost-docker repository is deprecated. To migrate from the 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 11+ 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.

Installing 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 or team image version.

  4. Redeploy Mattermost.

Troubleshooting your production deployment#

Docker#

If deploying on an M1 Mac and encountering permission issues in the Docker container, redo the third step and skip this command:

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

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

sudo systemctl enable --now docker

To remove all data and settings for your Mattermost deployment:

sudo rm -rf ./volumes

PostgreSQL#

You can change the Postgres username and/or password (recommended) in the .env file.

TLS & NGINX#

For an in-depth guide to configuring the TLS certificate and key for Nginx, please refer to this document in the repository.

Further help#

If you encounter other problems while installing Mattermost, please refer to our troubleshooting guide.