Local Machine Setup using Docker

The following instructions use Docker to install Mattermost in Preview Mode for exploring product functionality on a single machine using Docker.

Note: This configuration should not be used in production, as it’s using a known password string and contains other non-production configuration settings, and it does not support upgrade.

If you’re looking for a production installation with Docker, please see the Mattermost Production Docker Deployment Guide.

Note

If you have any problems installing Mattermost, see the troubleshooting guide. For help with inviting users to your system, see inviting team members and other getting started information. To submit an improvement or correction, click Edit at the top of this page.

One-line Docker Install

If you have Docker set up, Mattermost installs in one-line:

docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview

Otherwise, see step-by-step instructions:

macOS

  1. Install Docker for Mac
  2. Run: docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
  3. When docker is done fetching the image, open http://localhost:8065/ in your browser.

Windows 10

  1. Install Docker for Windows
  2. Run: docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
  3. When Docker is done fetching the image, open http://localhost:8065/ in your browser.

Ubuntu

  1. Follow the instructions at https://docs.docker.com/installation/ubuntulinux/ or use the summary below:

    sudo apt-get update
    sudo apt-get install wget
    wget -qO- https://get.docker.com/ | sh
    sudo usermod -aG docker <username>
    sudo service docker start
    newgrp docker
    
  2. Start Docker container:

    docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
    
  3. When Docker is done fetching the image, open http://localhost:8065/ in your browser.

Fedora

  1. Follow the instructions at https://docs.docker.com/engine/installation/linux/fedora/ or use the summary below:

    sudo dnf -y install dnf-plugins-core
    sudo dnf config-manager \
    --add-repo \
    https://download.docker.com/linux/fedora/docker-ce.repo
    sudo dnf install docker-ce docker-compose git # Accepting the new docker repository key
    sudo usermod -aG docker <username>
    sudo systemctl start docker
    
  2. Start Docker container:

    docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
    
  3. When Docker is done fetching the image, open http://localhost:8065/ in your browser.

Arch Linux

To install the preview on Arch Linux, see the installation guide on the Arch Linux wiki.

Sample SMTP Settings

Amazon SES

  • Set SMTP Username to [YOUR_SMTP_USERNAME]
  • Set SMTP Password to [YOUR_SMTP_PASSWORD]
  • Set SMTP Server to email-smtp.us-east-1.amazonaws.com
  • Set SMTP Port to 465
  • Set Connection Security to TLS

Postfix

  • Make sure Postfix is installed on the machine where Mattermost is installed
  • Set SMTP Username to (empty)
  • Set SMTP Password to (empty)
  • Set SMTP Server to localhost
  • Set SMTP Port to 25
  • Set Connection Security to (empty)

Gmail

  • Set SMTP Username to your_email@gmail.com
  • Set SMTP Password to your_password
  • Set SMTP Server to smtp.gmail.com
  • Set SMTP Port to 587
  • Set Connection Security to STARTTLS

Hotmail

  • Set SMTP Username to your_email@hotmail.com
  • Set SMTP Password to your_password
  • Set SMTP Server to smtp-mail.outlook.com
  • Set SMTP Port to 587
  • Set Connection Security to STARTTLS

Office365 / Outlook

  • Set SMTP Username to your_email@hotmail.com
  • Set SMTP Password to your_password
  • Set SMTP Server Name to smtp.office365.com
  • Set SMTP Port to 587
  • Set Connection Security to STARTTLS

Troubleshooting SMTP

TLS/STARTTLS Requirements

If you fill in SMTP Username and SMTP Password then you must set Connection Security to TLS or to STARTTLS

Troubleshooting using Logs

If you have issues with your SMTP install, from your Mattermost team site go to the main menu and open System Console -> Logs to look for error messages related to your setup. You can do a search for the error code to narrow down the issue. Sometimes ISPs require nuanced setups for SMTP and error codes can hint at how to make the proper adjustments.

For example, if System Console -> Logs has an error code reading:

Connection unsuccessful: Failed to add to email address - 554 5.7.1 <unknown[IP-ADDRESS]>: Client host rejected: Access denied

Search for 554 5.7.1 error and Client host rejected: Access denied.

Checking your SMTP server is reachable

  • Attempt to telnet to the email service to make sure the server is reachable.

  • You must run the following commands from the same machine or virtual instance where mattermost/bin/mattermost is located. So if you’re running Mattermost from Docker you need to docker exec -ti mattermost-dev /bin/bash

  • Telnet to the email server with telnet mail.example.com 25. If the command works you should see something like

    Trying 24.121.12.143...
    Connected to mail.example.com.
    220 mail.example.com NO UCE ESMTP
    
  • Then type something like HELO <your mail server domain>. If the command works you should see something like

    250-mail.example.com NO UCE
    250-STARTTLS
    250-PIPELINING
    250 8BITMIME
    

Note

For additional troubleshooting tips, see the troubleshooting guide. To submit an improvement or correction, click Edit at the top of this page.

Configuration Settings

See Configuration Settings documentation to customize your deployment.

Updating Docker Preview

To delete your existing Docker preview and run a new version use:

docker stop mattermost-preview
docker rm -v mattermost-preview

Accessing Your Container

  • If you wish to gain access to a shell on the container use:

    docker exec -ti mattermost-preview /bin/bash