README.md 6.96 KB
Newer Older
PICHOU Kyâne's avatar
PICHOU Kyâne committed
1
# Production Docker deployment for Mattermost
PICHOU Kyâne's avatar
PICHOU Kyâne committed
2

PICHOU Kyâne's avatar
PICHOU Kyâne committed
3
This project enables deployment of a Mattermost server in a multi-node production configuration using Docker.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
4
5
6

[![Build Status](https://travis-ci.org/mattermost/mattermost-docker.svg?branch=master)](https://travis-ci.org/mattermost/mattermost-docker)

PICHOU Kyâne's avatar
PICHOU Kyâne committed
7
Notes:
PICHOU Kyâne's avatar
PICHOU Kyâne committed
8
9
10
- 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)
PICHOU Kyâne's avatar
PICHOU Kyâne committed
11
12
13
14
15
16
17
- 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).

## Installation using Docker Compose

The following instructions deploy Mattermost in a production configuration using multi-node Docker Compose set up.

### Requirements
PICHOU Kyâne's avatar
PICHOU Kyâne committed
18

PICHOU Kyâne's avatar
PICHOU Kyâne committed
19
20
* [docker] (version `1.10.0+`)
* [docker-compose] (version `1.6.0+` to support Compose file version `2.0`)
PICHOU Kyâne's avatar
PICHOU Kyâne committed
21

PICHOU Kyâne's avatar
PICHOU Kyâne committed
22
### Choose Edition to Install
PICHOU Kyâne's avatar
PICHOU Kyâne committed
23

PICHOU Kyâne's avatar
PICHOU Kyâne committed
24
If you want to install Enterprise Edition, you can skip this section.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
25

PICHOU Kyâne's avatar
PICHOU Kyâne committed
26
27
28
29
To install the team edition, comment out the two following lines in docker-compose.yaml file:
```yaml
args:
  - edition=team
PICHOU Kyâne's avatar
PICHOU Kyâne committed
30
```
PICHOU Kyâne's avatar
PICHOU Kyâne committed
31
The `app` Dockerfile will read the `edition` build argument to install Team (`edition = 'team'`) or Entreprise (`edition != team`) edition.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
32

PICHOU Kyâne's avatar
PICHOU Kyâne committed
33
34
35
36
37
### 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
PICHOU Kyâne's avatar
PICHOU Kyâne committed
38

PICHOU Kyâne's avatar
PICHOU Kyâne committed
39
40
It is possible to use your own PostgreSQL database, or even use MySQL. But you will need to ensure that Application container can connect to the database (see [Application container](#application-container))

PICHOU Kyâne's avatar
PICHOU Kyâne committed
41
42
43
44
45
46
#### 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
PICHOU Kyâne's avatar
PICHOU Kyâne committed
47

PICHOU Kyâne's avatar
PICHOU Kyâne committed
48
49
50
51
52
53
54
55
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.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
56

PICHOU Kyâne's avatar
PICHOU Kyâne committed
57
58
59
60
61
### 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
PICHOU Kyâne's avatar
PICHOU Kyâne committed
62

PICHOU Kyâne's avatar
PICHOU Kyâne committed
63
64
65
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
PICHOU Kyâne's avatar
PICHOU Kyâne committed
66

PICHOU Kyâne's avatar
PICHOU Kyâne committed
67
68
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.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
69

PICHOU Kyâne's avatar
PICHOU Kyâne committed
70
71
72
If you choose to use MySQL instead of PostgreSQL, you should set a different datasource and SQL driver :
* `DB_PORT_NUMBER` : `3306`
* `MM_SQLSETTINGS_DRIVERNAME` : `mysql`
PICHOU Kyâne's avatar
PICHOU Kyâne committed
73
* `MM_SQLSETTINGS_DATASOURCE` : `MM_USERNAME:MM_PASSWORD@tcp(DB_HOST:DB_PORT_NUMBER)/MM_DBNAME?charset=utf8mb4,utf8&readTimeout=30s&writeTimeout=30s`
PICHOU Kyâne's avatar
PICHOU Kyâne committed
74
Don't forget to replace all entries (beginning by `MM_` and `DB_`) in `MM_SQLSETTINGS_DATASOURCE` with the real variables values.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
75

PICHOU Kyâne's avatar
PICHOU Kyâne committed
76
### Web server container
PICHOU Kyâne's avatar
PICHOU Kyâne committed
77
78
79
This image is optional, you should **not** use it when you have your own reverse-proxy. It is a simple front Web server for the Mattermost app container. If you use the provided `docker-compose.yml` file, you don't have to configure anything. But if your application container is reachable on custom host and/or port (eg. if you use a container provider), you should add those two environment variables :
* `APP_HOST`: application host address
* `APP_PORT_NUMBER`: application HTTP port
PICHOU Kyâne's avatar
PICHOU Kyâne committed
80

PICHOU Kyâne's avatar
PICHOU Kyâne committed
81
82
83
84
#### 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.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
85

PICHOU Kyâne's avatar
PICHOU Kyâne committed
86
### Starting/Stopping Docker
PICHOU Kyâne's avatar
PICHOU Kyâne committed
87

PICHOU Kyâne's avatar
PICHOU Kyâne committed
88
89
90
91
#### Start
```
docker-compose start
```
PICHOU Kyâne's avatar
PICHOU Kyâne committed
92

PICHOU Kyâne's avatar
PICHOU Kyâne committed
93
94
95
#### Stop
```
docker-compose stop
PICHOU Kyâne's avatar
PICHOU Kyâne committed
96
97
```

PICHOU Kyâne's avatar
PICHOU Kyâne committed
98
### Removing Docker
PICHOU Kyâne's avatar
PICHOU Kyâne committed
99

PICHOU Kyâne's avatar
PICHOU Kyâne committed
100
101
102
#### Remove the containers
```
docker-compose stop && docker-compose rm
PICHOU Kyâne's avatar
PICHOU Kyâne committed
103
104
```

PICHOU Kyâne's avatar
PICHOU Kyâne committed
105
106
107
108
#### Remove the data and settings of your Mattermost instance
```
sudo rm -rf volumes
```
PICHOU Kyâne's avatar
PICHOU Kyâne committed
109

PICHOU Kyâne's avatar
PICHOU Kyâne committed
110
## Update Mattermost to latest version
PICHOU Kyâne's avatar
PICHOU Kyâne committed
111

PICHOU Kyâne's avatar
PICHOU Kyâne committed
112
First, shutdown your containers to back up your data.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
113

PICHOU Kyâne's avatar
PICHOU Kyâne committed
114
115
116
```
docker-compose down
```
PICHOU Kyâne's avatar
PICHOU Kyâne committed
117

PICHOU Kyâne's avatar
PICHOU Kyâne committed
118
Back up your mounted volumes to save your data. If you use the default `docker-compose.yml` file proposed on this repository, your data is on `./volumes/` folder.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
119

PICHOU Kyâne's avatar
PICHOU Kyâne committed
120
Then run the following commands.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
121

PICHOU Kyâne's avatar
PICHOU Kyâne committed
122
123
124
125
126
```
git pull
docker-compose build
docker-compose up -d
```
PICHOU Kyâne's avatar
PICHOU Kyâne committed
127

PICHOU Kyâne's avatar
PICHOU Kyâne committed
128
Your Docker image should now be on the latest Mattermost version.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
129

PICHOU Kyâne's avatar
PICHOU Kyâne committed
130
131
## Upgrading to Team Edition 3.0.x from 2.x

PICHOU Kyâne's avatar
PICHOU Kyâne committed
132
133
134
135
136
137
138
139
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
docker-compose run app -upgrade_db_30
docker-compose up -d
```
PICHOU Kyâne's avatar
PICHOU Kyâne committed
140
141
See the [offical Upgrade Guide](http://docs.mattermost.com/administration/upgrade.html) for more details.

PICHOU Kyâne's avatar
PICHOU Kyâne committed
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
## Installation using Docker Swarm Mode

The following instructions deploy Mattermost in a production configuration using docker swarm mode on one node.
Running containerized applications on multi-node swarms involves specific data portability and replication handling that are not covered here.

### Requirements

* [docker] (1.12.0+)

### Swarm Mode Installation

First, create mattermost directory structure on the docker hosts:
```
mkdir -p /var/lib/mattermost/{cert,config,data,logs}
```

Then, fire up the stack in your swarm:
```
docker stack deploy -c contrib/swarm/docker-stack.yml mattermost
```

PICHOU Kyâne's avatar
PICHOU Kyâne committed
163
164
165
## Known Issues

* Do not modify the Listen Address in Service Settings.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
166
* Rarely `app` container fails to start because of "connection refused" to
PICHOU Kyâne's avatar
PICHOU Kyâne committed
167
168
  database. Workaround: Restart the container.

PICHOU Kyâne's avatar
PICHOU Kyâne committed
169
## More information
PICHOU Kyâne's avatar
PICHOU Kyâne committed
170
171
172
173

If you want to know how to use docker-compose, see [the overview
page](https://docs.docker.com/compose).

PICHOU Kyâne's avatar
PICHOU Kyâne committed
174
For the server configurations, see [prod-ubuntu.rst] of Mattermost.
PICHOU Kyâne's avatar
PICHOU Kyâne committed
175
176
177

[docker]: http://docs.docker.com/engine/installation/
[docker-compose]: https://docs.docker.com/compose/install/
PICHOU Kyâne's avatar
PICHOU Kyâne committed
178
[prod-ubuntu.rst]: https://docs.mattermost.com/install/install-ubuntu-1604.html