2019-11-08 23:15:03 +01:00
# Docker
2019-03-08 01:38:36 +01:00
2019-11-08 23:15:03 +01:00
The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad.
2019-03-08 01:38:36 +01:00
2019-11-08 23:17:34 +01:00
## Downloading from Docker Hub
2019-07-12 02:38:47 +02:00
If you are ok downloading a [prebuilt image from Docker Hub ](https://hub.docker.com/r/etherpad/etherpad ), these are the commands:
```bash
# gets the latest published version
docker pull etherpad/etherpad
2019-03-08 01:38:36 +01:00
2019-07-12 02:38:47 +02:00
# gets a specific version
2019-11-08 23:15:03 +01:00
docker pull etherpad/etherpad:1.8.0
2019-07-12 02:38:47 +02:00
```
2019-11-08 23:17:34 +01:00
## Build a personalized container
2019-07-12 02:38:47 +02:00
If you want to use a personalized settings file, **you will have to rebuild your image** .
All of the following instructions are as a member of the `docker` group.
2020-04-19 04:35:27 +02:00
By default, the Etherpad Docker image is built and run in `production` mode: no development dependencies are installed, and asset bundling speeds up page load time.
2019-03-08 01:38:36 +01:00
2019-11-08 23:17:34 +01:00
### Rebuilding with custom settings
2019-11-08 23:50:50 +01:00
Edit `<BASEDIR>/settings.json.docker` at your will. When rebuilding the image, this file will be copied inside your image and renamed to `setting.json` .
2019-03-08 01:38:36 +01:00
2019-03-21 01:37:19 +01:00
**Each configuration parameter can also be set via an environment variable**, using the syntax `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"` . For details, refer to `settings.json.template` .
2019-03-09 23:01:21 +01:00
2019-11-08 23:17:34 +01:00
### Rebuilding including some plugins
2019-07-12 02:32:34 +02:00
If you want to install some plugins in your container, it is sufficient to list them in the ETHERPAD_PLUGINS build variable.
The variable value has to be a space separated, double quoted list of plugin names (see examples).
2019-11-08 23:50:50 +01:00
Some plugins will need personalized settings. Just refer to the previous section, and include them in your custom `settings.json.docker` .
2019-07-12 02:32:34 +02:00
2019-11-08 23:17:34 +01:00
### Examples
2019-07-12 02:38:47 +02:00
2019-11-08 22:56:30 +01:00
Build a Docker image from the currently checked-out code:
2019-03-08 01:38:36 +01:00
```bash
docker build --tag < YOUR_USERNAME > /etherpad .
2019-07-12 02:38:47 +02:00
```
2019-03-08 01:38:36 +01:00
2019-07-12 02:32:34 +02:00
Include two plugins in the container:
```bash
docker build --build-arg ETHERPAD_PLUGINS="ep_codepad ep_author_neat" --tag < YOUR_USERNAME > /etherpad .
```
2019-11-08 23:17:34 +01:00
## Running your instance:
2019-03-08 01:38:36 +01:00
To run your instance:
```bash
2019-11-07 23:02:34 +01:00
docker run --detach --publish < DESIRED_PORT > :9001 < YOUR_USERNAME > /etherpad
2019-03-08 01:38:36 +01:00
```
2019-11-07 23:02:34 +01:00
And point your browser to `http://<YOUR_IP>:<DESIRED_PORT>`
2019-10-01 07:03:59 +02:00
2019-11-08 23:17:34 +01:00
## Options available by default
2019-10-01 07:03:59 +02:00
2019-11-08 23:50:50 +01:00
The `settings.json.docker` available by default enables some configuration to be set from the environment.
2019-10-01 07:03:59 +02:00
2020-04-19 22:34:19 +02:00
### General
2019-11-08 23:15:03 +01:00
2020-04-21 04:29:51 +02:00
| Variable | Description | Default |
| ------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TITLE` | The name of the instance | |
| `FAVICON` | favicon default name, or a fully specified URL to your own favicon | |
| `DEFAULT_PAD_TEXT` | The default text of a pad | |
| `IP` | IP which etherpad should bind at. Change to `::` for IPv6 | |
| `PORT` | port which etherpad should bind at | |
| `ADMIN_PASSWORD` | the password for the `admin` user (leave unspecified if you do not want to create it) | |
| `USER_PASSWORD` | the password for the first user `user` (leave unspecified if you do not want to create it) | |
2020-04-19 22:34:19 +02:00
### Database
2020-04-21 04:29:51 +02:00
| Variable | Description | Default |
| ------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| `DB_TYPE` | a database supported by https://www.npmjs.com/package/ueberdb2 | |
| `DB_HOST` | the host of the database | |
| `DB_PORT` | the port of the database | |
| `DB_NAME` | the database name | |
| `DB_USER` | a database user with sufficient permissions to create tables | |
| `DB_PASS` | the password for the database username | |
| `DB_CHARSET` | the character set for the tables (only required for MySQL) | |
| `DB_FILENAME` | in case `DB_TYPE` is `DirtyDB` , the database filename. | |
2020-04-19 22:34:19 +02:00
2020-04-21 04:24:32 +02:00
If your database needs additional settings, you will have to use a personalized `settings.json.docker` and rebuild the container (or otherwise put the updated `settings.json` inside your image).
2020-04-19 22:34:19 +02:00
### Skins
2020-04-21 04:29:51 +02:00
| Variable | Description | Default |
| --------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
| `SKIN_NAME` | either `no-skin` , `colibris` or an existing directory under `src/static/skins` | |
2020-04-19 22:34:19 +02:00
### Logging
2020-04-21 04:29:51 +02:00
| Variable | Description | Default |
| -------------------- | ---------------------------------------------------- | ------- |
| `LOGLEVEL` | valid values are `DEBUG` , `INFO` , `WARN` and `ERROR` | |
2020-04-19 22:34:19 +02:00
### Advanced
2020-04-21 04:29:51 +02:00
| Variable | Description | Default |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `SHOW_SETTINGS_IN_ADMIN_PAGE` | hide/show the settings.json in admin page | |
| `TRUST_PROXY` | set to `true` if you are using a reverse proxy in front of Etherpad (for example: Traefik for SSL termination via Let's Encrypt). This will affect security and correctness of the logs if not done | |
| `IMPORT_MAX_FILE_SIZE` | maximum allowed file size when importing a pad, in bytes. | |
| `IMPORT_EXPORT_MAX_REQ_PER_IP` | maximum number of import/export calls per IP. | |
| `IMPORT_EXPORT_RATE_LIMIT_WINDOW` | the call rate for import/export requests will be estimated in this time window (in milliseconds) | |
2020-04-19 22:34:19 +02:00
2019-10-01 07:03:59 +02:00
2019-11-08 23:17:34 +01:00
### Examples
2019-10-01 07:03:59 +02:00
Use a Postgres database, no admin user enabled:
```shell
docker run -d \
--name etherpad \
-p 9001:9001 \
-e 'DB_TYPE=postgres' \
-e 'DB_HOST=db.local' \
-e 'DB_PORT=4321' \
-e 'DB_NAME=etherpad' \
-e 'DB_USER=dbusername' \
-e 'DB_PASS=mypassword' \
etherpad/etherpad
```
Run enabling the administrative user `admin` :
```shell
docker run -d \
--name etherpad \
-p 9001:9001 \
-e 'ADMIN_PASSWORD=supersecret' \
etherpad/etherpad
```
2019-11-15 10:44:40 +01:00
Run a test instance running DirtyDB on a persistent volume:
```
docker run -d \
-v etherpad_data:/opt/etherpad-lite/var \
-p 9001:9001 \
etherpad/etherpad
```