search

jasl8r / docker-mattermost

Docker solution for mattermost
MIT License
15 stars 20 forks source link

readme

Docker Repository on Quay.io

Docker Mattermost

Introduction

Dockerfile to build a Mattermost container image.

Contributing

If you find this image useful here's how you can help:

Issues

Please file a issue request on the issues page.

Installation

Automated builds of the image are available on Dockerhub and is the recommended method of installation.

Note: Builds are also available on Quay.io

docker pull jasl8r/mattermost:3.5.1

You can also pull the latest tag which is built from the repository HEAD

docker pull jasl8r/mattermost:latest

Alternatively you can build the image locally.

docker build -t jasl8r/mattermost github.com/jasl8r/docker-mattermost

Quick Start

The quickest way to get started is using docker-compose.

wget https://raw.githubusercontent.com/jasl8r/docker-mattermost/master/docker-compose.yml

Generate and assign random strings to the MATTERMOST_SECRET_KEY, MATTERMOST_LINK_SALT, MATTERMOST_RESET_SALT and MATTERMOST_INVITE_SALT environment variables. Once set you should not change these values and ensure you backup these values.

Tip: You can generate a random string using pwgen -Bsv1 64.

Start Mattermost using:

docker-compose up

Alternatively, you can manually launch the mattermost container and the supporting mysql and redis containers by following this three step guide.

Step 1. Launch a mysql container

docker run --name mattermost-mysql -d \
    --env 'MYSQL_USER=mattermost' --env 'MYSQL_PASSWORD=password' \
    --env 'MYSQL_DATABASE=mattermost' --env 'MYSQL_ROOT_PASSWORD=password' \
    --volume /srv/docker/mattermost/mysql:/var/lib/mysql
    mysql:latest

Step 2. Launch the mattermost container

docker run --name mattermost -d \
    --link mattermost-mysql:mysql \
    --publish 8080:80 \
    --env 'MATTERMOST_SECRET_KEY=long-and-random-alphanumeric-string' \
    --env 'MATTERMOST_LINK_SALT=long-and-random-alphanumeric-string' \
    --env 'MATTERMOST_RESET_SALT=long-and-random-alphanumeric-string' \
    --env 'MATTERMOST_INVITE_SALT=long-and-random-alphanumeric-string' \
    --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
    jasl8r/mattermost:3.5.1

Please refer to Available Configuration Parameters to understand MATTERMOST_PORT and other configuration options

NOTE: Please allow a couple of minutes for the Mattermost application to start.

Point your browser to http://localhost:8080 and create your administrator account.

You should now have the Mattermost application up and ready for testing. If you want to use this image in production the please read on.

The rest of the document will use the docker command line. You can quite simply adapt your configuration into a docker-compose.yml file if you wish to do so.

Configuration

Data Store

Mattermost stores data in the file system for features like file uploads and avatars. To avoid losing this data you should mount a volume at,

SELinux users are also required to change the security context of the mount point so that it plays nicely with selinux.

mkdir -p /srv/docker/mattermost/mattermost
sudo chcon -Rt svirt_sandbox_file_t /srv/docker/mattermost/mattermost

Volumes can be mounted in docker by specifying the -v option in the docker run command.

docker run --name mattermost -d \
    --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
    jasl8r/mattermost:3.5.1

Database

Mattermost uses a database backend to store its data. You can configure this image to use MySQL.

MySQL

External MySQL Server

The image can be configured to use an external MySQL database. The database configuration should be specified using environment variables while starting the Mattermost image.

Before you start the Mattermost image create a user and database for mattermost.

CREATE USER 'mattermost'@'%.%.%.%' IDENTIFIED BY 'password';
CREATE DATABASE IF NOT EXISTS `mattermost` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`;
GRANT ALL PRIVILEGES ON `mattermost`.* TO 'mattermost'@'%.%.%.%';

We are now ready to start the Mattermost application.

Assuming that the mysql server host is 192.168.1.100

docker run --name mattermost -d \
    --env 'DB_ADAPTER=mysql' --env 'DB_HOST=192.168.1.100' \
    --env 'DB_NAME=mattermost' \
    --env 'DB_USER=mattermost' --env 'DB_PASS=password' \
    --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
    jasl8r/mattermost:3.5.1

Linking to MySQL Container

You can link this image with a mysql container for the database requirements. The alias of the mysql server container should be set to mysql while linking with the mattermost image.

If a mysql container is linked, only the DB_ADAPTER, DB_HOST and DB_PORT settings are automatically retrieved using the linkage. You may still need to set other database connection parameters such as the DB_NAME, DB_USER, DB_PASS and so on.

To illustrate linking with a mysql container, we will use the official mysql image. When using mysql in production you should mount a volume for the mysql data store.

First, lets pull the mysql image from the docker index.

docker pull mysql:latest

For data persistence lets create a store for the mysql and start the container.

SELinux users are also required to change the security context of the mount point so that it plays nicely with selinux.

mkdir -p /srv/docker/mattermost/mysql
sudo chcon -Rt svirt_sandbox_file_t /srv/docker/mattermost/mysql

The run command looks like this.

docker run --name mattermost-mysql -d \
    --env 'MYSQL_USER=mattermost' --env 'MYSQL_PASSWORD=password' \
    --env 'MYSQL_DATABASE=mattermost' --env 'MYSQL_ROOT_PASSWORD=password' \
    --volume /srv/docker/mattermost/mysql:/var/lib/mysql
    mysql:latest

The above command will create a database named mattermost and also create a user named mattermost with the password password with full/remote access to the mattermost database.

We are now ready to start the Mattermost application.

docker run --name mattermost -d --link mattermost-mysql:mysql \
    --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
    jasl8r/mattermost:3.5.1

Here the image will also automatically fetch the MYSQL_DATABASE, MYSQL_USER and MYSQL_PASSWORD variables from the mysql container as they are specified in the docker run command for the mysql container. This is made possible using the magic of docker links and works with the following images:

PostgreSQL

External PostgreSQL Server

The image also supports using an external PostgreSQL server. This is also controlled via environment variables.

CREATE ROLE mattermost with LOGIN CREATEDB PASSWORD 'password';
CREATE DATABASE mattermost;
GRANT ALL PRIVILEGES ON DATABASE mattermost to mattermost;

We are now ready to start the Mattermost application.

Assuming that the PostgreSQL server host is 192.168.1.100

docker run --name mattermost -d \
     --env 'DB_ADAPTER=postgres' --env 'DB_HOST=192.168.1.100' \
     --env 'DB_NAME=mattermost' \
     --env 'DB_USER=mattermost' --env 'DB_PASS=password' \
     --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
     jasl8r/mattermost:3.5.1

Linking to PostgreSQL Container

You can link this image with a postgres container for the database requirements. The alias of the postgres server container should be set to postgres while linking with the mattermost image.

If a postgres container is linked, only the DB_ADAPTER, DB_HOST and DB_PORT settings are automatically retrieved using the linkage. You may still need to set other database connection parameters such as the DB_NAME, DB_USER, DB_PASS and so on.

To illustrate linking with a postgres container, we will use the postgres image. When using postgres image in production you should mount a volume for the postgres data store. Please refer the postgres documentation for details.

First, lets pull the postgres image from the docker index.

docker pull postgres:latest

For data persistence lets create a store for the postgres and start the container.

SELinux users are also required to change the security context of the mount point so that it plays nicely with selinux.

mkdir -p /srv/docker/mattermost/postgres
sudo chcon -Rt svirt_sandbox_file_t /srv/docker/mattermost/postgres

The run command looks like this.

docker run --name mattermost-postgres -d \
    --env 'POSTGRES_USER=mattermost' --env 'POSTGRES_PASSWORD=password' \
    --volume /srv/docker/mattermost/postgres:/var/lib/postgresql \
    postgresql:latest

The above command will create a database named mattermost and also create a user named mattermost with the password password with access to the mattermost database.

We are now ready to start the Mattermost application.

docker run --name mattermost -d --link mattermost-postgres:postgres \
     --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
     jasl8r/mattermost:3.5.1

Here the image will also automatically fetch the POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD variables from the postgres container as they are specified in the docker run command for the postgres container. This is made possible using the magic of docker links and works with the official postgres image.

Mail

The mail configuration should be specified using environment variables while starting the Mattermost image.

If you are using Gmail then all you need to do is:

docker run --name mattermost -d \
    --env 'SMTP_USER=USER@gmail.com' --env 'SMTP_PASS=PASSWORD'
    --env 'SMTP_DOMAIN=www.gmail.com' \
    --env 'SMTP_HOST=smtp.gmail.com' --env 'SMTP_PORT=587' \
    --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
    jasl8r/mattermost:3.5.1

Please refer the Available Configuration Parameters section for the list of SMTP parameters that can be specified.

SSL

The mattermost container and default docker compose configuration only provides an insecure HTTP interface. To ensure privacy mattermost should be run behind a proxy like nginx, haproxy or hipache to perform HTTPS termination via SSL offload. Configuring and utilizing proxies beyond using the sample nginx docker compose solution presented below are outside the scope of this document.

A docker compose file, samples/nginx/docker-compose.yml is included to run nginx as a proxy in front of mattermost. This configuration requires runtime data provided as docker volumes:

When using CA certified certificates, the private key and certificate are provided to you by the CA. When using self-signed certificates you need to generate these files yourself. Skip to Strengthening the Server Security section if you are armed with CA certified SSL certificates.

Generation of Self Signed Certificates

Generation of self-signed SSL certificates involves a simple 3 step procedure.

STEP 1: Create the server private key

openssl genrsa -out mattermost.key 2048

STEP 2: Create the certificate signing request (CSR)

openssl req -new -key mattermost.key -out mattermost.csr

STEP 3: Sign the certificate using the private key and CSR

openssl x509 -req -days 3650 -in mattermost.csr -signkey mattermost.key -out mattermost.crt

Congratulations! you have now generated an SSL certificate that will be valid for 10 years.

Strengthening the Server Security

This section provides you with instructions to strengthen your server security. To achieve this we need to generate stronger DHE parameters.

openssl dhparam -out dhparam.pem 2048

Installation of the SSL Certificates

Out of the four files generated above, we need to install the mattermost.key, mattermost.crt and dhparam.pem files for the nginx server. The CSR file is not needed, but do make sure you safely backup the file (in case you ever need it again). The configuration template, mattermost.template, also needs to be provided to nginx.

The default path that the nginx application is configured to look for the SSL certificates is at /etc/nginx. Following the conventions in this guide, the certificates and configuration can be provided as docker volumes by installing them in /srv/docker/mattermost/nginx/.

mkdir -p /srv/docker/mattermost/nginx
cp mattermost.key /srv/docker/mattermost/nginx/
cp mattermost.crt /srv/docker/mattermost/nginx/
cp dhparam.pem /srv/docker/mattermost/nginx/
chmod 400 /srv/docker/mattermost/nginx/mattermost.key

Running Mattermost with HTTPS

Download the necessary docker-compose files.

wget https://raw.githubusercontent.com/jasl8r/docker-mattermost/master/samples/nginx/docker-compose.yml
wget https://raw.githubusercontent.com/jasl8r/docker-mattermost/master/samples/nginx/mattermost.template
mv mattermost.template /srv/docker/mattermost/nginx/

As in the Quick Start section, generate and assign random strings to the MATTERMOST_SECRET_KEY, MATTERMOST_LINK_SALT, MATTERMOST_RESET_SALT and MATTERMOST_INVITE_SALT environment variables. In addition, set the NGINX_HOST variable for the nginx service.

In this configuration, any requests made over the plain HTTP protocol will automatically be redirected to use the HTTPS protocol. The default template file assumes that mattermost will be hosted on ports 80 and 443. If you want to host on different ports and retain the functionality of the HTTP redirect, be sure to update the mattermost.template accordingly.

Start Mattermost using:

docker-compose up

Point your browser to https://localhost:8443 to access mattermost over a secure connection.

GitLab Integration

Mattermost allows users to sign in using GitLab as an OAuth provider. Configuring GitLab does not prevent standard Mattermost authentication from continuing to work. Users can choose to sign in using any of the configured mechanisms.

Refer to the Mattermost documentation for additional information.

To enable GitLab SSO you must register your application with GitLab. GitLab will generate a Client ID and secret for you to use. Please refer to the GitLab documentation for the procedure to generate the Client ID and secret with GitLab.

Once you have the Client ID and secret generated, configure the SSO credentials using the GITLAB_ID, GITLAB_SECRET, GITLAB_SCOPE, GITLAB_AUTH_ENDPOINT, GITLAB_TOKEN_ENDPOINT and GITLAB_API_ENDPOINT environment variables.

Available Configuration Parameters

Please refer the docker run command options for the --env-file flag where you can specify all required environment variables in a single file. This will save you from writing a potentially long docker run command. Alternatively you can use docker-compose.

Below is the complete list of available options that can be used to customize your Mattermost installation.

Maintenance

Upgrading

Mattermost releases new versions on the 16th of every month. I will update this project shortly after a release is made.

To upgrade to newer Mattermost releases, simply follow this 4 step upgrade procedure.

docker pull jasl8r/mattermost:3.5.1
docker stop mattermost
docker rm mattermost

Backup your database and local file storage by your preferred backup method. All of the necessary data is located under /srv/docker/mattermost if the docker volume conventions of this guide are followed.

docker run --name mattermost -d [OPTIONS] jasl8r/mattermost:3.5.1

Upgrading to Version 3

With Mattermost version 3.0.0, the database must be destructively migrated to support the new global user model. This upgrade may be performed automatically or interactively using the built-in Mattermost upgrade mechanism. Due to the destructive and pervasive nature of this upgrade, it is imperative that you perform a backup of the database before upgrading.

In order to automatically upgrade the database, simply add the MATTERMOST_MIGRATION_DEFAULT_TEAM environment variable with the name of primary team used during the migration.

docker run --name mattermost -d --link mattermost-postgres:postgres \
     --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
     --env 'MATTERMOST_MIGRATION_DEFAULT_TEAM=myteam' \
     jasl8r/mattermost:3.5.1

Manually perform the migration by running the app:migrate command and follow the interactive prompt.

docker run -it --name mattermost -d --link mattermost-postgres:postgres \
     --volume /srv/docker/mattermost/mattermost:/opt/mattermost/data \
     jasl8r/mattermost:3.5.1 app:migrate

Shell Access

For debugging and maintenance purposes you may want access the containers shell. If you are using docker version 1.3.0 or higher you can access a running containers shell using docker exec command.

docker exec -it mattermost bash

References