Improve README
This commit is contained in:
PICHOU Kyâne
parent
0fddf35ac5
commit
ea748c2e52
133
README.md
133
README.md
@ -5,8 +5,8 @@ This project enables deployment of a Mattermost server in a multi-node productio
|
||||
[](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,39 +21,61 @@ 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
|
||||
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.
|
||||
|
||||
1. Put your SSL certificate as `./volumes/web/cert/cert.pem` and the private key that has
|
||||
### 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
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
2. Build and run mattermost
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
3. Open `https://your.domain` with your web browser.
|
||||
|
||||
### Install without SSL certificate
|
||||
|
||||
1. Build and run mattermost
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
2. Open `http://your.domain` with your web browser.
|
||||
|
||||
## Starting/Stopping
|
||||
|
||||
### Start
|
||||
@ -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/
|
||||
|
||||
Reference in New Issue
Block a user