Environment Variables of the XWiki Docker Image
Reference
When a container is started from the XWiki Docker Image (e.g., using Docker Run, Docker Compose or Docker Swarm), Docker automatically executes the /usr/local/bin/docker-entrypoint.sh script inside the container. This script reads the provided environment variables and initializes XWiki by generating the necessary configuration files and setting up connections. The environment variables can also be provided to the container as files containing their values (see the "File-based equivalent" column), in order to support Docker secrets. The following environment variables can be passed, or their equivalents:
| Environment Variable | Description of Environment Variable | File-based equivalent | Description of File-based equivalent |
|---|---|---|---|
| DB_USER | The user name used by XWiki to read/write to the DB. | DB_USER_FILE | The location, inside the container, of a file containing the value for DB_USER. |
| DB_PASSWORD | The user password used by XWiki to read/write to the DB. | DB_PASSWORD_FILE | The location, inside the container, of a file containing the value for DB_PASSWORD. |
| DB_DATABASE | The name of the XWiki database to use/create. | DB_DATABASE_FILE | The location, inside the container, of a file containing the value for DB_DATABASE. |
| DB_HOST | The name of the host (or docker container) containing the database. Default is "db". | DB_HOST_FILE | The location, inside the container, of a file containing the value for DB_HOST. |
| XWiki 17.10.11+, 18.4.3+, 18.6.0+ DB_PORT | The port on which the database listens. When not set, the JDBC driver's default port is used: 3306 for MySQL and MariaDB, 5432 for PostgreSQL. | DB_PORT_FILE | The location, inside the container, of a file containing the value for DB_PORT. |
| XWiki 17.10.11+, 18.4.3+, 18.6.0+ SOLR_BASE_URL | The base URL of an externally configured Solr instance (for example https://solr.example.com/solr). When left empty (the default), XWiki uses its embedded Solr instance. | SOLR_BASE_URL_FILE | The location, inside the container, of a file containing the value for SOLR_BASE_URL. |
| CONTEXT_PATH | The name of the context path under which XWiki will be deployed in Tomcat. If not specified then it'll be deployed as ROOT. If you had set this environment property and later on, recreate the XWiki container without passing it (i.e., you wish to deploy XWiki as ROOT again), then you'll need to edit the xwiki.cfg file in your mapped local permanent directory and set xwiki.webapppath=. | ||
| JDBC_PARAMS | Custom JDBC parameters to pass to the database connection. Setting this value overwrites the default parameters used (which depend on the DB used). The value must start with a question mark and the content be XML-encoded. For example: ?useSSL=false&connectionTimeZone=LOCAL&allowPublicKeyRetrieval=true. | JDBC_PARAMS_FILE | The location, inside the container, of a file containing the value for JDBC_PARAMS. |
| JAVA_OPTS | The JVM options used to start Tomcat, for example to increase the heap size. The image's own default options (-Xmx1024m, allowing encoded slashes and backslashes in URLs, and seeding from /dev/urandom) are each kept unless the value you provide already sets them. |
XWiki <17.10.11, <18.4.3, <18.6.0 Earlier images have INDEX_HOST and INDEX_PORT variables (and their _FILE equivalents) in place of SOLR_BASE_URL, and a remote Solr cannot be configured through them. See External Solr for XWiki in Docker.
FAQ
Can I use both an environment variable and its _FILE equivalent at the same time?
No. For each configuration value, the normal environment variable and _FILE environment variable are mutually exclusive. Providing values for both variables will result in an error.
Can I also customize the Java runtime used by XWiki?
Yes. You can customize the Java runtime by setting the JAVA_OPTS environment variable in the Docker container. For example, see Debug XWiki Remotely in Docker.
