Local Machine Setup using Docker¶
The following instructions use Docker to install Mattermost in Preview Mode for exploring product functionality on a single machine.
Note: This configuration should not be used in production, as it uses a known password string, contains other non-production configuration settings, and 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
When Docker is done fetching the image, open http://localhost:8065/ in your browser.
Otherwise, follow the step-by-step instructions:
macOS¶
Install Docker for Mac
Run:
docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
When Docker is done fetching the image, open
http://localhost:8065/
in your browser.
Windows 10¶
Install Docker for Windows
Run:
docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
When Docker is done fetching the image, open
http://localhost:8065/
in your browser.
Ubuntu¶
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
Start Docker container:
docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
When Docker is done fetching the image, open
http://localhost:8065/
in your browser.
Fedora¶
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
Start Docker container:
docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
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.
Setting up SMTP Email (Recommended)¶
The default single-container Docker instance for Mattermost is designed
for product evaluation, and sets SendEmailNotifications=false
so the
product can function without enabling email. To see the product’s full
functionality, enabling SMTP email is recommended.
To enable email, configure an SMTP email service as follows:
Set up an SMTP email sending service (if you don’t yet have an SMTP service with credentials)
- Any SMTP email service can be used, you just need the following
information:
Server Name
,Port
,SMTP Username
, andSMTP Password
.- If you don’t have an SMTP service, here are simple instructions
to set one up with Amazon Simple Email Service (SES):
Go to Amazon SES console then
SMTP Settings > Create My SMTP Credentials
Copy the
Server Name
,Port
,SMTP Username
, andSMTP Password
for Step 2 below.From the
Domains
menu set up and verify a new domain, then enableGenerate DKIM Settings
for the domain.We recommend you set up Sender Policy Framework (SPF) and/or Domain Keys Identified Mail (DKIM) for your email domain.
Choose a sender address like
mattermost@example.com
and clickSend a Test Email
to verify setup is working correctly.
Configure SMTP settings
Open the System Console by logging into an existing team and accessing “System Console” from the main menu.
- Alternatively, if a team doesn’t yet exist, go to
http://dockerhost:8065/
in your browser, create a team, then from the main menu click System Console
Go to the Authentication > Email tab and configure the following:
Allow Sign Up With Email:
true
Go to the Notifications > Email tab and configure the following:
Send Email Notifications:
true
Notification Display Name: Display name on email account sending notifications
Notification Email Address: Email address displayed on email account used to send notifications
SMTP Username:
SMTP Username
from Step 1SMTP Password:
SMTP Password
from Step 1SMTP Server:
SMTP Server
from Step 1SMTP Port:
SMTP Port
from Step 1Connection Security:
TLS (Recommended)
Then click Save
Then click Test Connection
If the test failed please look in OTHER > Logs for any errors that look like
[EROR] /api/v4/email/test ...
(Optional) Go to the Security > Sign Up tab and configure the following:
Enable Email Invitations:
true
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
Warning
Additional configuration is required in Google to allow SMTP email to relay through their servers. See SMTP relay: Route outgoing non-Gmail messages through Google for the required steps.
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.Telnet to the email server with
telnet mail.example.com 25
. If the command works you should see something likeTrying 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 like250-mail.example.com NO UCE 250-STARTTLS 250-PIPELINING 250 8BITMIME
Note
As we’re not installing telnet by default on the official docker images you either need to use ping
on those or install telnet yourself either directly or by modifying the Dockerfile.
Note
For further assistance, review the Troubleshooting forum for previously reported errors, or join the Mattermost user community for troubleshooting help. To submit an improvement or correction to this page, click Edit in the top-right corner of the 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