From ea748c2e526b884caeb565ae5462244278667502 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?PICHOU=20Ky=C3=A2ne?= Date: Sun, 16 Jul 2017 12:33:41 +0200 Subject: [PATCH 1/2] Improve README --- README.md | 129 +++++++++++++++++++++--------------------------------- 1 file changed, 49 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index f3e75a2..0d95be1 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@ This project enables deployment of a Mattermost server in a multi-node productio [![Build Status](https://travis-ci.org/mattermost/mattermost-docker.svg?branch=master)](https://travis-ci.org/mattermost/mattermost-docker) Notes: -- The default Mattermost edition for this repo has changed from team edition to enterprise edition. Please see [Choose Edition](#choose-edition-to-install) section. -- To install this Docker project on AWS Elastic Beanstalk please see [AWS Elastic Beanstalk Guide](./contrib/aws/README.md). +- The default Mattermost edition for this repo has changed from Team Edition to Enterprise Edition. Please see [Choose Edition](#choose-edition-to-install) section. +- To install this Docker project on AWS Elastic Beanstalk please see [AWS Elastic Beanstalk Guide](contrib/aws/README.md). - To run Mattermost on Kubernetes you can start with the [manifest examples in the kubernetes folder](contrib/kubernetes/README.md) - To install Mattermost without Docker directly onto a Linux-based operating systems, please see [Admin Guide](https://docs.mattermost.com/guides/administrator.html#installing-mattermost). @@ -21,38 +21,60 @@ The following instructions deploy Mattermost in a production configuration using ### Choose Edition to Install -If you want to install enterprise edition, you can skip this section. +If you want to install Enterprise Edition, you can skip this section. -To install the team edition, comment out the following line in docker-compose.yaml file: +To install the Team Edition, comment out the following line in docker-compose.yaml file: ``` dockerfile: Dockerfile-enterprise ``` -### Database +### Database container +This repository offer a Docker image for the Mattermost database. It is a customized PostgreSQL image that you should configure with following environment variables : +* `POSTGRES_USER`: database username +* `POSTGRES_PASSWORD`: database password +* `POSTGRES_DB`: database name -Make sure to set the appropriate values for `MM_USERNAME`, `MM_PASSWORD` and `MM_DBNAME`. +#### AWS +If deploying to AWS, you could also set following variables to enable [Wal-E](https://github.com/wal-e/wal-e) backup to S3 : +* `AWS_ACCESS_KEY_ID`: AWS access key +* `AWS_SECRET_ACCESS_KEY`: AWS secret +* `WALE_S3_PREFIX`: AWS s3 bucket name +* `AWS_REGION`: AWS region -### Install with SSL certificate - -1. Put your SSL certificate as `./volumes/web/cert/cert.pem` and the private key that has - no password as `./volumes/web/cert/key-no-password.pem`. If you don't have - them you may generate a self-signed SSL certificate. - -2. Build and run mattermost -``` -docker-compose up -d +All four environment variables are required. It will enable completed WAL segments sent to archive storage (S3). The base backup and clean up can be done through the following command: +```bash +# Base backup +docker exec mattermost-db su - postgres sh -c "/usr/bin/envdir /etc/wal-e.d/env /usr/local/bin/wal-e backup-push /var/lib/postgresql/data" +# Keep the most recent 7 base backups and remove the old ones +docker exec mattermost-db su - postgres sh -c "/usr/bin/envdir /etc/wal-e.d/env /usr/local/bin/wal-e delete --confirm retain 7" ``` +Those tasks can be executed through a cron job or systemd timer. -3. Open `https://your.domain` with your web browser. +### Application container +Application container run the Mattermost application. You should configure it with following environment variables : +* `MM_USERNAME`: database username +* `MM_PASSWORD`: database password +* `MM_DBNAME`: database name -### Install without SSL certificate +If your database use some custom host and port, it is also possible to configure them : +* `DB_HOST`: database host address +* `DB_PORT_NUMBER`: database port -1. Build and run mattermost -``` -docker-compose up -d -``` +If you use a Mattermost configuration file on a different location than the default one (`/mattermost/config/config.json`) : +* `MM_CONFIG`: configuration file location inside the container. -2. Open `http://your.domain` with your web browser. +If you choose to use MySQL instead of PostgreSQL, you should set a different datasource : +* `MM_SQLSETTINGS_DATASOURCE` : "$MM_USERNAME:$MM_PASSWORD@tcp($DB_HOST:$DB_PORT_NUMBER)/$MM_DBNAME?charset=utf8mb4,utf8&readTimeout=30s&writeTimeout=30s" + +### Web server container +This image is optional, you should not use it you have your own reverse-proxy. It is a simple front Web server for the Mattermost app container. +* `MATTERMOST_ENABLE_SSL`: whether to enable SSL +* `PLATFORM_PORT_80_TCP_PORT`: port that Mattermost image is listening on + +#### Install with SSL certificate +Put your SSL certificate as `./volumes/web/cert/cert.pem` and the private key that has +no password as `./volumes/web/cert/key-no-password.pem`. If you don't have +them you may generate a self-signed SSL certificate. ## Starting/Stopping @@ -83,68 +105,15 @@ docker-compose up -d docker-compose stop && docker-compose rm ``` -### Remove the data and settings of your mattermost instance +### Remove the data and settings of your Mattermost instance ``` sudo rm -rf volumes ``` -## Database Backup - -When AWS S3 environment variables are specified on db docker container, it enables [Wal-E](https://github.com/wal-e/wal-e) backup to S3. - -```bash -docker run -d --name mattermost-db \ - -e AWS_ACCESS_KEY_ID=XXXX \ - -e AWS_SECRET_ACCESS_KEY=XXXX \ - -e WALE_S3_PREFIX=s3://BUCKET_NAME/PATH \ - -e AWS_REGION=us-east-1 - -v ./volumes/db/var/lib/postgresql/data:/var/lib/postgresql/data - -v /etc/localtime:/etc/localtime:ro - db -``` - -All four environment variables are required. It will enable completed WAL segments sent to archive storage (S3). The base backup and clean up can be done through the following command: - -```bash -# base backup -docker exec mattermost-db su - postgres sh -c "/usr/bin/envdir /etc/wal-e.d/env /usr/local/bin/wal-e backup-push /var/lib/postgresql/data" -# keep the most recent 7 base backups and remove the old ones -docker exec mattermost-db su - postgres sh -c "/usr/bin/envdir /etc/wal-e.d/env /usr/local/bin/wal-e delete --confirm retain 7" -``` -Those tasks can be executed through a cron job or systemd timer. - -## Customization - -Customization can be done through environment variables. - -### Mattermost App Image - -* `MM_USERNAME`: database username, must be the same as one in DB image -* `MM_PASSWORD`: database password, must be the same as one in DB image -* `MM_DBNAME`: database name, must be the same as one in DB image -* `DB_HOST`: database host address -* `DB_PORT_NUMBER`: database port -* `MM_CONFIG`: configuration file location. It can be used when config is mounted in a different location. - -### Mattermost DB Image - -* `MM_USERNAME`: database username, must be the same as on in App image -* `MM_PASSWORD`: database password, must be the same as on in App image -* `MM_DBNAME`: database name, must be the same as on in App image -* `AWS_ACCESS_KEY_ID`: aws access key, used for db backup -* `AWS_SECRET_ACCESS_KEY`: aws secret, used for db backup -* `WALE_S3_PREFIX`: aws s3 bucket name, used for db backup -* `AWS_REGION`: aws region, used for db backup - -### Mattermost Web Image - -* `MATTERMOST_ENABLE_SSL`: whether to enable SSL -* `PLATFORM_PORT_80_TCP_PORT`: port that Mattermost image is listening on - ## Upgrading to Team Edition 3.0.x from 2.x -You need to migrate your database before upgrading mattermost to 3.0.x from -2.x. Run these commands in the latest mattermost-docker directory. +You need to migrate your database before upgrading Mattermost to `3.0.x` from +`2.x`. Run these commands in the latest `mattermost-docker` directory. ``` docker-compose rm -f app docker-compose build app @@ -156,7 +125,7 @@ See the [offical Upgrade Guide](http://docs.mattermost.com/administration/upgrad ## Known Issues * Do not modify the Listen Address in Service Settings. -* Rarely 'app' container fails to start because of "connection refused" to +* Rarely `app` container fails to start because of "connection refused" to database. Workaround: Restart the container. ## More information @@ -164,7 +133,7 @@ See the [offical Upgrade Guide](http://docs.mattermost.com/administration/upgrad If you want to know how to use docker-compose, see [the overview page](https://docs.docker.com/compose). -For the server configurations, see [prod-ubuntu.rst] of mattermost. +For the server configurations, see [prod-ubuntu.rst] of Mattermost. [docker]: http://docs.docker.com/engine/installation/ [docker-compose]: https://docs.docker.com/compose/install/ From b74145fad2d7470af709ef2be8a344093e3feef6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ky=C3=A2ne=20Pichou?= Date: Sun, 16 Jul 2017 12:38:23 +0200 Subject: [PATCH 2/2] Fix datasource option in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0d95be1..ff692b6 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ If you use a Mattermost configuration file on a different location than the defa * `MM_CONFIG`: configuration file location inside the container. If you choose to use MySQL instead of PostgreSQL, you should set a different datasource : -* `MM_SQLSETTINGS_DATASOURCE` : "$MM_USERNAME:$MM_PASSWORD@tcp($DB_HOST:$DB_PORT_NUMBER)/$MM_DBNAME?charset=utf8mb4,utf8&readTimeout=30s&writeTimeout=30s" +* `MM_SQLSETTINGS_DATASOURCE` : `"$MM_USERNAME:$MM_PASSWORD@tcp($DB_HOST:$DB_PORT_NUMBER)/$MM_DBNAME?charset=utf8mb4,utf8&readTimeout=30s&writeTimeout=30s"` ### Web server container This image is optional, you should not use it you have your own reverse-proxy. It is a simple front Web server for the Mattermost app container.