# Docker The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad. ## Downloading from Docker Hub 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 # gets a specific version docker pull etherpad/etherpad:1.8.0 ``` ## Build a personalized container 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. 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. ### Rebuilding with custom settings Edit `/settings.json.docker` at your will. When rebuilding the image, this file will be copied inside your image and renamed to `setting.json`. **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`. ### Rebuilding including some plugins 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). Some plugins will need personalized settings. Just refer to the previous section, and include them in your custom `settings.json.docker`. ### Examples Build a Docker image from the currently checked-out code: ```bash docker build --tag /etherpad . ``` Include two plugins in the container: ```bash docker build --build-arg ETHERPAD_PLUGINS="ep_codepad ep_author_neat" --tag /etherpad . ``` ## Running your instance: To run your instance: ```bash docker run --detach --publish :9001 /etherpad ``` And point your browser to `http://:` ## Options available by default The `settings.json.docker` available by default enables some configuration to be set from the environment. ### General | 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) | | ### Database | 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. | | 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). ### Skins | Variable | Description | Default | | --------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- | | `SKIN_NAME` | either `no-skin`, `colibris` or an existing directory under `src/static/skins` | | ### Logging | Variable | Description | Default | | -------------------- | ---------------------------------------------------- | ------- | | `LOGLEVEL` | valid values are `DEBUG`, `INFO`, `WARN` and `ERROR` | | ### Advanced | 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) | | ### Examples 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 ``` 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 ```