Steps

To run XWiki on the official Jetty Docker image, as follows:

1. Download the XWiki WAR file for the version you need.
2. Extract the WAR file into a directory named xwiki. This directory is referred to as XWIKI_HOME.
3. Configure a relational database. If the database also runs in a Docker container, place both containers on the same Docker network and use its container or service name instead of localhost in the connection URL.
4. Create a directory on your host machine to store XWiki's permanent data (attachments, configurations, extensions). This directory is referred to as XWIKI_PERMDIR.
5. (Optional) Open XWIKI_HOME/WEB-INF/xwiki.properties and set the permanent directory path:

   environment.permanentDirectory=/var/lib/jetty/xwiki-data

   If you skip this step, you can pass the path as a JVM system property when running the container (see next step).
6. Run the Jetty Docker container:

   docker run -d \
     -v /path/to/xwiki:/var/lib/jetty/webapps/xwiki \
     -v /path/to/permdir:/var/lib/jetty/xwiki-data \
     -p 8080:8080 \
     -e JAVA_OPTIONS="-Dxwiki.data.dir=/var/lib/jetty/xwiki-data" \
     jetty:12-jre17

   If you configured environment.permanentDirectory in xwiki.properties (step 4), you can omit the -e JAVA_OPTIONS argument.
7. Open http://localhost:8080/xwiki/bin/view/Main/ in a browser. XWiki starts in the container and serves its Home page once the UI is installed.

FAQ

Which modules do I need for Jetty 12?

Jetty 12 requires specifying the environment module. The module depends on your XWiki version:

• XWiki 17.x and above (jakarta): ee10-deploy, ee10-webapp, ee10-jstl
• XWiki 16.x and below (javax): ee8-deploy, ee8-webapp, ee8-jstl

Pass the modules on the docker run command line: docker run ... jetty:12 --module=ee10-deploy,ee10-webapp,ee10-jstl.

The list of modules used by XWiki is maintained in the xwiki.mod file used by the demo packaging.

Do I need a database?

Yes, XWiki requires a database. For quick testing, you can copy the HSQLDB JAR into XWIKI_HOME/WEB-INF/lib. For production, configure an external database (such as PostgreSQL or MySQL).

Can the database run in a separate Docker container?

Yes, this is the recommended setup. Create a shared Docker network (e.g. docker network create xwiki-net), start both the database and the Jetty container with --network xwiki-net, and reference the database container by its --name instead of localhost in hibernate.cfg.xml.

Should I use Docker Compose instead of separate docker run commands?

For production setups, consider using Docker Compose to run XWiki and the database together. Compose automatically places all services defined in the same file on a shared network, so you don't need to create one manually.

Related

• Configure Jetty.
• Configure Tomcat for XWiki in Docker.