galexrt/xwiki repository overview

⁠What is XWiki

XWiki⁠ is a free wiki software platform written in Java with a design emphasis on extensibility. XWiki is an enterprise wiki. It includes WYSIWYG editing, OpenDocument based document import/export, semantic annotations and tagging, and advanced permissions management.

As an application wiki, XWiki allows for the storing of structured data and the execution of server side script within the wiki interface. Scripting languages including Velocity, Groovy, Python, Ruby and PHP can be written directly into wiki pages using wiki macros. User-created data structures can be defined in wiki documents and instances of those structures can be attached to wiki documents, stored in a database, and queried using either Hibernate query language or XWiki's own query language.

XWiki.org's extension wiki⁠ is home to XWiki extensions ranging from code snippets⁠ which can be pasted into wiki pages to loadable core modules. Many of XWiki Enterprise's features are provided by extensions which are bundled with it.

⁠Table of contents

• Introduction⁠
• How to use this image⁠
  • Pulling existing image⁠
    • Using docker run⁠
    • Using docker-compose⁠
    • Using Docker Swarm⁠
  • Using an external Solr service⁠
    • Preparing Solr container⁠
    • Docker run example⁠
    • Docker Compose example⁠
  • Configuring Tomcat⁠
  • Building⁠
• Upgrading XWiki⁠
• Details for the xwiki image⁠
  • Configuration Options⁠
  • Passing JVM options⁠
  • Miscellaneous⁠
• For Maintainers⁠
  • Update Docker Images⁠
  • Testing Docker Images⁠
  • Clean Up⁠
• License⁠
• Support⁠
• Contribute⁠
• Credits⁠

⁠Introduction

The goal is to provide a production-ready XWiki system running in Docker. This is why:

• The OS is based on Debian and not on some smaller-footprint distribution like Alpine
• Several containers are used with Docker Compose: one for the DB and another for XWiki + Servlet container. This allows the ability to run them on different machines for example.

⁠How to use this image

You should first install Docker⁠ on your machine.

Then there are several options:

1. Pull the xwiki image from DockerHub.
2. Get the sources of this project⁠ and build them.

⁠Pulling an existing image

You need to run 2 containers:

• One for the XWiki image
• One for the database image to which XWiki connects to

⁠Using docker run

Start by creating a dedicated docker network:

docker network create -d bridge xwiki-nw

Then run a container for the database and make sure it's configured to use an UTF8 encoding. The following databases are supported out of the box:

• MySQL
• MariaDB
• PostgreSQL

⁠Starting MySQL

We will bind mount two local directories to be used by the MySQL container:

• one to be used at database initialization to set permissions (see below),
• another to contain the data put by XWiki inside the MySQL database, so that when you stop and restart MySQL you don't find yourself without any data.

For example:

• /my/path/mysql-init
• /my/path/mysql

You need to make sure these directories exist, and then create a file under the /my/path/mysql-init directory (you can name it the way you want, for example init.sql), with the following content:

grant all privileges on *.* to xwiki@'%'

This will provide enough permissions for the xwiki user to create new schemas which is required to be able to create sub-wikis.

Note: Make sure the directories you are mounting into the container are fully-qualified, and aren't relative paths.

docker run --net=xwiki-nw --name mysql-xwiki -v /my/path/mysql:/var/lib/mysql -v /my/path/mysql-init:/docker-entrypoint-initdb.d -e MYSQL_ROOT_PASSWORD=xwiki -e MYSQL_USER=xwiki -e MYSQL_PASSWORD=xwiki -e MYSQL_DATABASE=xwiki -d mysql:5.7 --character-set-server=utf8mb4 --collation-server=utf8mb4_bin --explicit-defaults-for-timestamp=1

You should adapt the command line to use the passwords that you wish for the MySQL root password and for the xwiki user password (make sure to also change the GRANT command).

Notes:

• If you're using MySQL8, you also need to configure the mysql_native_password authentication plugin the native password mechanism that XWiki uses to connect:

  docker run --net=xwiki-nw --name mysql-xwiki -v /my/path/mysql:/var/lib/mysql -v /my/path/mysql-init:/docker-entrypoint-initdb.d -e MYSQL_ROOT_PASSWORD=xwiki -e MYSQL_USER=xwiki -e MYSQL_PASSWORD=xwiki -e MYSQL_DATABASE=xwiki -d mysql:5.7 --character-set-server=utf8mb4 --collation-server=utf8mb4_bin --explicit-defaults-for-timestamp=1 --default-authentication-plugin=mysql_native_password
  

  Copy

• If you want to use utf8 instead of utf8mb4 (you won't have emojis though), you could use instead: character-set-server=utf8 --collation-server=utf8_bin.

• The explicit-defaults-for-timestamp parameter was introduced in MySQL 5.6.6 and will thus work only for that version and beyond. If you are using an older MySQL version, please use the following instead:

  docker run --net=xwiki-nw --name mysql-xwiki -v /my/path/mysql:/var/lib/mysql -v /my/path/mysql-init:/docker-entrypoint-initdb.d -e MYSQL_ROOT_PASSWORD=xwiki -e MYSQL_USER=xwiki -e MYSQL_PASSWORD=xwiki -e MYSQL_DATABASE=xwiki -d mysql:5.7 --character-set-server=utf8mb4 --collation-server=utf8mb4_bin
  

  Copy

⁠Starting MariaDB

This is exactly similar to starting MySQL and you should thus follow exactly the same steps as for MySQL. The only thing to change is the docker image for MariaDB: instead of mysql:<tag>, use mariadb:<tag>. For example: mariadb:10.3.

Full command example:

docker run --net=xwiki-nw --name mysql-xwiki -v /my/path/mysql:/var/lib/mysql -v /my/path/mysql-init:/docker-entrypoint-initdb.d -e MYSQL_ROOT_PASSWORD=xwiki -e MYSQL_USER=xwiki -e MYSQL_PASSWORD=xwiki -e MYSQL_DATABASE=xwiki -d mariadb:10.3 --character-set-server=utf8mb4 --collation-server=utf8mb4_bin --explicit-defaults-for-timestamp=1

⁠Starting PostgreSQL

We will bind mount a local directory to be used by the PostgreSQL container to contain the data put by XWiki inside the database, so that when you stop and restart PostgreSQL you don't find yourself without any data. For example:

• /my/path/postgres

You need to make sure this directory exists, before proceeding.

Note Make sure the directory you specify is specified with the fully-qualified path, not a relative path.

docker run --net=xwiki-nw --name postgres-xwiki -v /my/path/postgres:/var/lib/postgresql/data -e POSTGRES_ROOT_PASSWORD=xwiki -e POSTGRES_USER=xwiki -e POSTGRES_PASSWORD=xwiki -e POSTGRES_DB=xwiki -e POSTGRES_INITDB_ARGS="--encoding=UTF8" -d postgres:9.5

You should adapt the command line to use the passwords that you wish for the PostgreSQL root password and for the xwiki user password.

⁠Starting XWiki

We will also bind mount a local directory for the XWiki permanent directory (contains application config and state), for example:

• /my/path/xwiki

Note Make sure the directory you specify is specified with the fully-qualified path, not a relative path.

Ensure this directory exists, and then run XWiki in a container by issuing one of the following command.

For MySQL:

docker run --net=xwiki-nw --name xwiki -p 8080:8080 -v /my/path/xwiki:/usr/local/xwiki -e DB_USER=xwiki -e DB_PASSWORD=xwiki -e DB_DATABASE=xwiki -e DB_HOST=mysql-xwiki xwiki:lts-mysql-tomcat

For PostgreSQL:

docker run --net=xwiki-nw --name xwiki -p 8080:8080 -v /my/path/xwiki:/usr/local/xwiki -e DB_USER=xwiki -e DB_PASSWORD=xwiki -e DB_DATABASE=xwiki -e DB_HOST=postgres-xwiki xwiki:lts-postgres-tomcat

Be careful to use the same DB username, password and database names that you've used on the first command to start the DB container. Also, please don't forget to add a -e DB_HOST= environment variable with the name of the previously created DB container so that XWiki knows where its database is.

At this point, XWiki should start in interactive blocking mode, allowing you to see logs in the console. Should you wish to run it in "detached mode", just add a "-d" flag in the previous command.

docker run -d --net=xwiki-nw ...

⁠Using docker-compose

Another solution is to use the Docker Compose files we provide.

⁠For MySQL

• wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/11/mysql-tomcat/mysql/xwiki.cnf: This will download the MySQL configuration (UTF8, etc)
  • If you don't have wget or prefer to use curl: curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/11/mysql-tomcat/mysql/xwiki.cnf -o xwiki.cnf
• wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/11/mysql-tomcat/mysql/init.sql: This will download some SQL to execute at startup for MySQL
  • If you don't have wget or prefer to use curl: curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/11/mysql-tomcat/mysql/init.sql -o init.sql
• wget -O docker-compose.yml https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/docker-compose-mysql.yml
  • If you don't have wget or prefer to use curl: curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/docker-compose-mysql.yml -o docker-compose.yml
• You can edit the compose file retrieved to change the default username/password and other environment variables.
• docker-compose up

For reference here's a minimal Docker Compose file using MySQL that you could use as an example (full example here⁠):

version: '2'
networks:
  bridge:
    driver: bridge
services:
  web:
    image: "xwiki:lts-mysql-tomcat"
    container_name: xwiki-mysql-tomcat-web
    depends_on:
      - db
    ports:
      - "8080:8080"
    environment:
      - DB_USER=xwiki
      - DB_PASSWORD=xwiki
      - DB_HOST=xwiki-mysql-db
    volumes:
      - xwiki-data:/usr/local/xwiki
    networks:
      - bridge
  db:
    image: "mysql:5.7"
    container_name: xwiki-mysql-db
    volumes:
      - ./xwiki.cnf:/etc/mysql/conf.d/xwiki.cnf
      - mysql-data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    environment:
      - MYSQL_ROOT_PASSWORD=xwiki
      - MYSQL_USER=xwiki
      - MYSQL_PASSWORD=xwiki
      - MYSQL_DATABASE=xwiki
    networks:
      - bridge
volumes:
  mysql-data: {}
  xwiki-data: {}

⁠For PostgreSQL

• wget -O docker-compose.yml https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/docker-compose-postgres.yml
  • If you don't have wget or prefer to use curl: curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/docker-compose-postgres.yml -o docker-compose.yml
• You can edit the compose file retrieved to change the default username/password and other environment variables.
• docker-compose up

For reference here's a minimal Docker Compose file using PostgreSQL that you could use as an example (full example here⁠):

version: '2'
networks:
  bridge:
    driver: bridge
services:
  web:
    image: "xwiki:lts-postgres-tomcat"
    container_name: xwiki-postgres-tomcat-web
    depends_on:
      - db
    ports:
      - "8080:8080"
    environment:
      - DB_USER=xwiki
      - DB_PASSWORD=xwiki
      - DB_HOST=xwiki-postgres-db
    volumes:
      - xwiki-data:/usr/local/xwiki
    networks:
      - bridge
  db:
    image: "postgres:9.5"
    container_name: xwiki-postgres-db
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_ROOT_PASSWORD=xwiki
      - POSTGRES_PASSWORD=xwiki
      - POSTGRES_USER=xwiki
      - POSTGRES_DB=xwiki
      - POSTGRES_INITDB_ARGS="--encoding=UTF8"
    networks:
      - bridge
volumes:
  postgres-data: {}
  xwiki-data: {}

⁠Using Docker Swarm

Here are some examples of using this image with Docker Swarm. These examples leverage additional features of Docker Swarm such as Docker secrets, and Docker configs. As such, these examples require Docker to be in swarm mode.

You can read more about these features and Docker swarm mode here:

• Docker swarm mode⁠
• Creating Docker secrets⁠
• Creating Docker configs⁠

⁠MySQL Example

This example presupposes the existence of the Docker secrets xwiki-db-username, xwiki-db-password and xwiki-db-root-password, and the Docker config xwiki-mysql-config.

You can create these secrets and configs with the following:

• echo ${MY_XWIKI_USER:-xwiki} | docker secret create xwiki-db-username -
• echo $(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 16 | head -n 1) | docker secret create xwiki-db-password -
• echo $(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 16 | head -n 1) | docker secret create xwiki-db-root-password -
• docker config create xwiki-mysql-config /path/to/mysql/xwiki.cnf

To deploy this example, save the following YAML as xwiki-stack.yaml, then run:

• docker stack deploy -c xwiki-stack.yaml xwiki

version: '3.3'
services:
  web:
    image: "xwiki:lts-mysql-tomcat"
    ports:
      - "8080:8080"
    environment:
      - DB_USER_FILE=/run/secrets/xwiki-db-username
      - DB_PASSWORD_FILE=/run/secrets/xwiki-db-password
      - DB_DATABASE=xwiki
      - DB_HOST=db
    volumes:
      - xwiki-data:/usr/local/xwiki
    secrets:
      - xwiki-db-username
      - xwiki-db-password
  db:
    image: "mysql:5.7"
    volumes:
      - mysql-data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/xwiki-db-root-password
      - MYSQL_USER_FILE=/run/secrets/xwiki-db-username
      - MYSQL_PASSWORD_FILE=/run/secrets/xwiki-db-password
      - MYSQL_DATABASE=xwiki
    secrets:
      - xwiki-db-username
      - xwiki-db-password
      - xwiki-db-root-password
    configs: 
      - source: mysql-config
        target: /etc/mysql/conf.d/xwiki.cnf
volumes:
  mysql-data:
  xwiki-data:
secrets:
  xwiki-db-username:
    external:
      name: xwiki-db-username
  xwiki-db-password:
    external:
      name: xwiki-db-password
  xwiki-db-root-password:
    external:
      name: xwiki-db-root-password
configs:
  mysql-config:
    external:
      name: xwiki-mysql-config

⁠PostgreSQL Example

This example presupposes the existence of the Docker secrets xwiki-db-username, xwiki-db-password, and xwiki-db-root-password.

You can create these secrets with the following:

• echo ${MY_XWIKI_USER:-xwiki} | docker secret create xwiki-db-username -
• echo $(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 16 | head -n 1) | docker secret create xwiki-db-password -
• echo $(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 16 | head -n 1) | docker secret create xwiki-db-root-password -

To deploy this example, save the following YAML as xwiki-stack.yaml then run:

• docker stack deploy -c xwiki-stack.yaml xwiki

version: '3.3'
services:
  web:
    image: "xwiki:lts-postgres-tomcat"
    ports:
      - "8080:8080"
    environment:
      - DB_USER_FILE=/run/secrets/xwiki-db-username
      - DB_PASSWORD_FILE=/run/secrets/xwiki-db-password
      - DB_DATABASE=xwiki
      - DB_HOST=db
    volumes:
      - xwiki-data:/usr/local/xwiki
    secrets:
      - xwiki-db-username
      - xwiki-db-password
  db:
    image: "postgres:9.5"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_ROOT_PASSWORD_FILE=/run/secrets/xwiki-db-root-password
      - POSTGRES_USER_FILE=/run/secrets/xwiki-db-username
      - POSTGRES_PASSWORD_FILE=/run/secrets/xwiki-db-password
      - POSTGRES_DB=xwiki
    secrets:
      - xwiki-db-username
      - xwiki-db-password
      - xwiki-db-root-password
volumes:
  postgres-data:
  xwiki-data:
secrets:
  xwiki-db-username:
    external:
      name: xwiki-db-username
  xwiki-db-password:
    external:
      name: xwiki-db-password
  xwiki-db-root-password:
    external:
      name: xwiki-db-root-password

⁠Using an external Solr service

From the XWiki Solr Search API documentation⁠:

This image provides the configuration parameters INDEX_HOST and INDEX_PORT which are used to configure xwiki.properties with:

solr.type=remote  
solr.remote.url=http://$INDEX_HOST:$INDEX_PORT/solr/xwiki

⁠Preparing Solr container

The simplest way to create an external Solr service is using the official Solr image⁠.

• Select the appropriate XWiki Solr configuration JAR from here⁠ (Note: it's usually better to synchronize it with your version of XWiki)
• Place this JAR in a directory along side solr-init.sh that you can fetch from the docker-xwiki repository⁠
• Ensure that this directory is owned by the Solr user and group chown -R 8983:8983 /path/to/solr/init/directory
• Launch the Solr container and mount this directory at /docker-entrypoint-initdb.d
• This will execute solr-init.sh on container startup and prepare the XWiki core with the contents from the given JAR
• If you want to persist the Solr index outside of the container with a bind mount, make sure that that directory is owned by the Solr user and group chown 8983:8983 /my/path/solr

⁠Docker run example

Start your chosen database container normally using the docker run command above, this example happens to assume MySQL was chosen.

The command below will configure the Solr container to initialize based on the contents of /path/to/solr/init/directory/ and save its data on the host in a /my/path/solr directory:

docker run \
  --net=xwiki-nw \
  --name solr-xwiki \
  -v /path/to/solr/init/directory:/docker-entrypoint-initdb.d \
  -v /my/path/solr:/opt/solr/server/solr/xwiki \
  -d solr:7.2

Then start the XWiki container, the below command is nearly identical to that specified in the Starting XWiki section above, except that it includes the -e INDEX_HOST= environment variable which specifies the hostname of the Solr container.

docker run \
  --net=xwiki-nw \
  --name xwiki \
  -p 8080:8080 \
  -v /my/path/xwiki:/usr/local/xwiki \
  -e DB_USER=xwiki \
  -e DB_PASSWORD=xwiki \
  -e DB_DATABASE=xwiki \
  -e DB_HOST=mysql-xwiki \
  -e INDEX_HOST=solr-xwiki \
  -d xwiki:lts-mysql-tomcat

⁠Docker Compose example

The below compose file assumes that ./solr contains solr-init.sh and the configuration JAR file.

version: '2'
networks:
  bridge:
    driver: bridge
services:
  web:
    image: "xwiki:lts-mysql-tomcat"
    container_name: xwiki-web
    depends_on:
      - db
      - index
    ports:
      - "8080:8080"
    environment:
      - XWIKI_VERSION=xwiki
      - DB_USER=xwiki
      - DB_PASSWORD=xwiki
      - DB_DATABASE=xwiki
      - DB_HOST=xwiki-db
      - INDEX_HOST=xwiki-index
    volumes:
      - xwiki-data:/usr/local/xwiki
    networks:
      - bridge
  db:
    image: "mysql:5.7"
    container_name: xwiki-db
    volumes:
      - ./mysql/xwiki.cnf:/etc/mysql/conf.d/xwiki.cnf
      - mysql-data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=xwiki
      - MYSQL_USER=xwiki
      - MYSQL_PASSWORD=xwiki
      - MYSQL_DATABASE=xwiki
    networks:
      - bridge
  index:
    image: "solr:7.2"
    container_name: xwiki-index
    volumes:
      - ./solr:/docker-entrypoint-initdb.d
      - solr-data:/opt/solr/server/solr
    networks:
      - bridge
volumes:
  mysql-data: {}
  xwiki-data: {}
  solr-data: {}

⁠Configuring Tomcat

If you need to configure Tomcat (for example to setup a reverse proxy configuration), you'll need to mount the Tomcat configuration directory (/usr/local/tomcat/conf) inside the image onto your local host.

If you want to modify the existing configuration rather than provide a brand new one, you'll need to use docker cp to copy the configuration from the container to your local host.

Here are some example steps you can follow:

• Create a docker container from the XWiki image with docker create.
  • Example: docker create --name xwiki xwiki:lts-mysql-tomcat.
• Copy the Tomcat configuration from the container to the host to start with some existing configuration files, using docker cp.
  • Example: sudo docker cp xwiki:/usr/local/tomcat/conf /tmp/tomcat.
• Modify the Tomcat configuration locally to bring the changes you need.
• Delete the created XWiki container since it was only used to copy the configuration files and we'll need to create a new one with different parameters.
  • Example: docker rm xwiki.
• Run the container with the Tomcat mount and the other parameters.
  • Example: docker run --net=xwiki-nw --name xwiki -p 8080:8080 -v /tmp/xwiki:/usr/local/xwiki -v /tmp/tomcat:/usr/local/tomcat/conf -e DB_USER=xwiki -e DB_PASSWORD=xwiki -e DB_DATABASE=xwiki -e DB_HOST=mysql-xwiki xwiki:lts-mysql-tomcat

⁠Building

This allows you to rebuild the XWiki docker image locally. Here are the steps:

• Install Git and run git clone https://github.com/xwiki-contrib/docker-xwiki.git or download the sources from the GitHub UI. Then go to the directory corresponding to the docker tag you wish to use. For example: cd 8/mysql-tomcat
  • The 8/mysql-tomcat directory will get you the latest released XWiki version of the 8.x cycle running on Tomcat and for MySQL.
  • The 8/postgres-tomcat directory will get you the latest released XWiki version of the 8.x cycle running on Tomcat and for MySQL.
  • The 9/mysql-tomcat directory will get you the latest released XWiki version of the 9.x cycle running on Tomcat and for MySQL.
  • etc.
• Run docker-compose up
• Start a browser and point it to http://localhost:8080

Note that if you want to set a custom version of XWiki you can edit the .env file and set the values you need in there. It's also possible to override them on the command line with docker-compose run -e "XWIKI_VERSION=8.4.4".

Note that docker-compose up will automatically build the XWiki image on the first run. If you need to rebuild it you can issue docker-compose up --build. You can also build the image with docker build . -t xwiki-mysql-tomcat:latest for example.

You can also just build the image by issuing docker build -t xwiki . and then use the instructions from above to start XWiki and the database using docker run ....

⁠Upgrading XWiki

You've installed an XWiki docker image and used it and now comes the time when you'd like to upgrade XWiki to a newer version.

If you've followed the instructions above you've mapped the XWiki permanent directory to a local directory on your host.

All you need to do to upgrade is to stop the running XWiki cont