XWiki is a free and open source wiki software platform written in Java with a design emphasis on extensibility.
See the documentation of XWiki.org or Wikipedia's article about XWiki to know more about XWiki.
- Introduction
- How to use this image
- Upgrading XWiki
- Details for the xwiki image
- Using an external Solr service
- Troubleshooting
- For Maintainers
- License
- Support
- Contribute
- Credits
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 provides the ability to run them on different machines for example.
You should first install Docker on your machine.
Then, there are several options:
- Pull the
xwiki
image from DockerHub. - Get the sources of this project and build them.
You need to run 2 containers:
- One for the XWiki image
- One for the database image to which XWiki connects to
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
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:9.1 --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:
-
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:9.1 --character-set-server=utf8mb4 --collation-server=utf8mb4_bin
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:11.5
.
Full command example:
docker run --net=xwiki-nw --name mysql-xwiki -v /my/path/mariadb:/var/lib/mysql -v /my/path/mariadb-init:/docker-entrypoint-initdb.d -e MYSQL_ROOT_PASSWORD=xwiki -e MYSQL_USER=xwiki -e MYSQL_PASSWORD=xwiki -e MYSQL_DATABASE=xwiki -d mariadb:11.5 --character-set-server=utf8mb4 --collation-server=utf8mb4_bin --explicit-defaults-for-timestamp=1
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:17
You should adapt the command line to use the passwords that you wish for the PostgreSQL root password and for the xwiki user password.
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:stable-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:stable-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 ...
Another solution is to use the Docker Compose files we provide.
wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/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 usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mysql-tomcat/mysql/init.sql -o init.sql
- If you don't have
wget -O docker-compose.yml https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mysql-tomcat/docker-compose.yml
- If you don't have
wget
or prefer to usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mysql-tomcat/docker-compose.yml -o docker-compose.yml
- If you don't have
wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mysql-tomcat/.env
: This contains default configuration values you should edit (version of XWiki to use, etc)- If you don't have
wget
or prefer to usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mysql-tomcat/.env -o .env
- If you don't have
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:stable-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:9.1"
container_name: xwiki-mysql-db
volumes:
- 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
command:
- "--character-set-server=utf8mb4"
- "--collation-server=utf8mb4_bin"
- "--explicit-defaults-for-timestamp=1"
networks:
- bridge
volumes:
mysql-data: {}
xwiki-data: {}
wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mariadb-tomcat/mariadb/init.sql
: This will download some SQL to execute at startup for MariaDB- If you don't have
wget
or prefer to usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mariadb-tomcat/mariadb/init.sql -o init.sql
- If you don't have
wget -O docker-compose.yml https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mariadb-tomcat/docker-compose.yml
- If you don't have
wget
or prefer to usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mariadb-tomcat/docker-compose.yml -o docker-compose.yml
- If you don't have
wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mariadb-tomcat/.env
: This contains default configuration values you should edit (version of XWiki to use, etc)- If you don't have
wget
or prefer to usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/mariadb-tomcat/.env -o .env
- If you don't have
docker-compose up
For reference here's a minimal Docker Compose file using MariaDB that you could use as an example (full example here):
version: '2'
networks:
bridge:
driver: bridge
services:
web:
image: "xwiki:stable-mariadb-tomcat"
container_name: xwiki-mariadb-tomcat-web
depends_on:
- db
ports:
- "8080:8080"
environment:
- DB_USER=xwiki
- DB_PASSWORD=xwiki
- DB_HOST=xwiki-mariadb-db
volumes:
- xwiki-data:/usr/local/xwiki
networks:
- bridge
db:
image: "mariadb:11.5"
container_name: xwiki-mariadb-db
volumes:
- mariadb-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
command:
- "--character-set-server=utf8mb4"
- "--collation-server=utf8mb4_bin"
- "--explicit-defaults-for-timestamp=1"
networks:
- bridge
volumes:
mariadb-data: {}
xwiki-data: {}
wget -O docker-compose.yml https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/postgres-tomcat/docker-compose.yml
- If you don't have
wget
or prefer to usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/postgres-tomcat/docker-compose.yml -o docker-compose.yml
- If you don't have
wget https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/postgres-tomcat/.env
: This contains default configuration values you should edit (version of XWiki to use, etc)- If you don't have
wget
or prefer to usecurl
:curl -fSL https://raw.githubusercontent.com/xwiki-contrib/docker-xwiki/master/16/postgres-tomcat/.env -o .env
- If you don't have
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:stable-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:17"
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: {}
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:
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 -
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:stable-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:9.1"
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
command:
- "--character-set-server=utf8mb4"
- "--collation-server=utf8mb4_bin"
- "--explicit-defaults-for-timestamp=1"
secrets:
- xwiki-db-username
- xwiki-db-password
- xwiki-db-root-password
volumes:
mysql-data:
xwiki-data:
secrets:
xwiki-db-username:
name: xwiki-db-username
external: true
xwiki-db-password:
name: xwiki-db-password
external: true
xwiki-db-root-password:
name: xwiki-db-root-password
external: true
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:stable-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:17"
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:
name: xwiki-db-username
external: true
xwiki-db-password:
name: xwiki-db-password
external: true
xwiki-db-root-password:
name: xwiki-db-root-password
external: true
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 13/mysql-tomcat
- The
13/mysql-tomcat
directory will get you the latest released XWiki version of the 13.x cycle running on Tomcat and for MySQL. - The
13/postgres-tomcat
directory will get you the latest released XWiki version of the 13.x cycle running on Tomcat and for MySQL. - The
12/mysql-tomcat
directory will get you the latest released XWiki version of the 12.x cycle running on Tomcat and for MySQL. - etc.
- The
- 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=12.10.10"
.
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 ...
.
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, and you've done the same for each configuration files that you have needed to customize (see Configuration Files)
Follow these steps:
- Stop the running XWiki container. You should keep your DB container running.
- Check the Release Notes for all releases that happened between your current version and the new version you're upgrading to, as there could be some manual steps to perform (such as updating your XWiki configuration files).
- Start the new version of the XWiki container that you want to upgrade to.
The first time you create a container out of the xwiki image, a shell script (/usr/local/bin/docker-entrypoint.sh
) is executed in the container to setup some configuration. The following environment variables can be passed:
DB_USER
: The user name used by XWiki to read/write to the DB.DB_PASSWORD
: The user password used by XWiki to read/write to the DB.DB_DATABASE
: The name of the XWiki database to use/create.DB_HOST
: The name of the host (or docker container) containing the database. Default is "db".INDEX_HOST
: The hostname of an externally configured Solr instance. Defaults to "localhost", and configures an embedded Solr instance.INDEX_PORT
: The port used by an externally configured Solr instance. Defaults to 8983.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), the you'll need to edit the
xwiki.cfg
file in your mapped local permanent directory and setxwiki.webapppath=
.
- 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), the you'll need to edit the
JDBC_PARAMS
: Custom JDB parameters to pass to the JBC 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
.
In order to support Docker secrets, these configuration values can also be given to the container as files containing that value.
DB_USER_FILE
: The location, inside the container, of a file containing the value forDB_USER
DB_PASSWORD_FILE
: The location, inside the container, of a file containing the value forDB_PASSWORD
DB_DATABASE_FILE
: The location, inside the container, of a file containing the value forDB_DATABASE
DB_HOST_FILE
: The location, inside the container, of a file containing the value forDB_HOST
INDEX_HOST_FILE
: The location, inside the container, of a file containing the value forINDEX_HOST
INDEX_PORT_FILE
: The location, inside the container, of a file containing the value forINDEX_PORT
JDBC_PARAMS_FILE
: The location, inside the container, of a file containing the value forJDBC_PARAMS
Note: 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.
It's possible to pass JVM options to Tomcat by defining the JAVA_OPTS
environment property.
See an example below, used to perform remote debugging of an XWiki instance.
To perform remote debugging on an XWiki instance started using a Docker container, you'll need to do 2 things:
- Expose the debugging port (using the
-p
option when executingdocker run
) - Configure Tomcat to start Java in debug mode (using the
JAVA_OPTS
environment variable)
This can be achieved with:
docker run --net=xwiki-nw --name xwiki -p 8080:8080 -v xwiki:/usr/local/xwiki -e DB_USER=xwiki -e DB_PASSWORD=xwiki -e DB_DATABASE=xwiki -e DB_HOST=mysql-xwiki -e JAVA_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=*:5005" -p 5005:5005 xwiki
You will find below all the XWiki configuration files that exist and that you may want to configure. In order to do so, the strategy is to map Docker volumes for these files from your local host machine to their locations inside the XWiki Docker image.
Full list of configuration files, with their location inside the XWiki Docker image:
- Permanent directory:
/usr/local/xwiki
xwiki.cfg
:$WEB-INF/xwiki.cfg
xwiki.properties
:$WEB-INF/xwiki.properties
hibernate.cfg.xml
:$WEB-INF/hibernate.cfg.xml
- Clustering (JGroups directory):
$WEB-INF/observation/remote/jgroups
logback.xml
(logging) :$WEB-INF/classes/logback.xml
web.xml
:$WEB-INF/web.xml
where:
$WEB-INF
is the location of the XWiki WAR'sWEB-INF
directory, at/usr/local/tomcat/webapps/$CONTEXT_PATH/WEB-INF/
.$CONTEXT_PATH
is the Servlet context deployment name for the XWiki webapp, by default it'sROOT
.
Notes:
- In the past, the first 3 configuration files listed above (
xwiki.cfg
,xwiki.properties
andhibernate.cfg.xml
) had a special handling, and they were copied automatically on the first XWiki container start, from the XWiki image into the local permanent directory. This was removed starting with XWiki 16.6.0/15.10.12. However, in order to preserve backward compatibility, if these files are found in the permanent directory, they are copied on container start to their location inside the container. - It's recommended to only map volumes for configuration files that you need to customize. This is because when you upgrade you'll need to perform a merge between XWiki's default configuration files and the ones you modified. If you haven't modified them, then there's no merge to do.
If your config files are in a local /my/xwiki/config/path
directory, you would use the following for docker run
:
docker run ... -v /my/xwiki/config/path/xwiki.cfg:/usr/local/tomcat/webapps/ROOT/WEB-INF/xwiki.cfg -v ... xwiki
[...]
services:
web:
image: "xwiki:stable-mysql-tomcat"
[...]
volumes:
- xwiki-data:/usr/local/xwiki
- xwiki-cfg:/usr/local/tomcat/webapps/ROOT/WEB-INF/xwiki.cfg
- xwiki-properties:/usr/local/tomcat/webapps/ROOT/WEB-INF/xwiki.properties
- xwiki-hibernate:/usr/local/tomcat/webapps/ROOT/WEB-INF/hibernate.cfg.xml
- xwiki-jgroups:/usr/local/tomcat/webapps/ROOT/WEB-INF/observation/remote/jgroups
- xwiki-logback:/usr/local/tomcat/webapps/ROOT/WEB-INF/classes/logback.xml
- xwiki-webxml:/usr/local/tomcat/webapps/ROOT/WEB-INF/web.xml
[...]
volumes:
[...]
xwiki-data: {}
xwiki-cfg: {}
xwiki-properties: {}
xwiki-hibernate: {}
xwiki-jgroups: {}
xwiki-logback: {}
xwiki-webxml: {}
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:stable-mysql-tomcat
.
- Example:
- 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
.
- Example:
- 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
.
- Example:
- 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:stable-mysql-tomcat
- Example:
Volumes:
If you don't map any volume when using docker run
or if you use docker-compose
then Docker will create some internal volumes attached to your containers as follows.
-
Two volumes are created:
- A volume named
<prefix>_mysql-data
or<prefix>_postgres-data
that contains the database data. - A volume named
<prefix>_xwiki-data
that contains XWiki's permanent directory.
- A volume named
-
To find out where those volumes are located on your local host machine you can inspect them with
docker volume inspect <volume name>
. To find the volume name, you can list all volumes withdocker volume ls
. -
Note that on Mac OSX, Docker runs inside the xhyve VM and thus the paths you get when inspecting the volumes are relative to this. Thus, you need to get into that VM if you need to access the volume data.
MySQL:
- To issue some mysql commands:
- Find the container id with
docker ps
- Execute bash in the mysql container:
docker exec -it <containerid> bash -l
- Once inside the mysql container execute the
mysql
command:mysql --user=xwiki --password=xwiki
- Find the container id with
From the XWiki Solr Search API documentation:
By default XWiki ships with an embedded Solr. This is mostly for ease of use but the embedded instance is not really recommended by the Solr team so you might want to externalize it when starting to have a wiki with a lots of pages. Solr is using a lot of memory and a standalone Solr instance is generally better in term of speed than the embedded one. It should not be much noticeable in a small wiki but if you find yourself starting to have memory issues and slow search results you should probably try to install and setup an external instance of Solr using the guide.
Also the speed of the drive where the Solr index is located can be very important because Solr/Lucene is quite filesystem intensive. For example putting it in a SSD might give a noticeable boost.
You can also find more Solr-specific performance details on https://wiki.apache.org/solr/SolrPerformanceProblems. Standalone Solr also comes with a very nice UI, along with monitoring and test tools.
This image provides the configuration parameters INDEX_HOST
and INDEX_PORT
which are used to configure xwiki.properties
with:
solr.type=remote
solr.remote.baseURL=http://$INDEX_HOST:$INDEX_PORT/solr
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
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:9
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:stable-mysql-tomcat
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:stable-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:9.1"
container_name: xwiki-db
volumes:
- mysql-data:/var/lib/mysql
environment:
- MYSQL_ROOT_PASSWORD=xwiki
- MYSQL_USER=xwiki
- MYSQL_PASSWORD=xwiki
- MYSQL_DATABASE=xwiki
command:
- "--character-set-server=utf8mb4"
- "--collation-server=utf8mb4_bin"
- "--explicit-defaults-for-timestamp=1"
networks:
- bridge
index:
image: "solr:9"
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: {}
If you're hitting a problem when running the XWiki docker image related to the use of eclipse-temurin in the XWiki base image, there are 2 workarounds:
- Make sure you use a Docker version >= 20.10.16
- If that's not possible run the XWiki Docker container without the default seccomp profile
-
Create a JIRA issue on the XDOCKER project with subject
Upgrade stable version to <version>
. -
Update the version of XWiki in the
build.gradle
file found in the XWiki Docker repository (clone it locally first). -
To know how to generate the sha256, check the doc inside
build.gradle
. You need to download in advance the XWiki WAR file and run the according command in order to generate.-
On Linux, use the following one-liner and replace the value of the
VERSION
variable accordingly:VERSION="12.10.10"; wget http://nexus.xwiki.org/nexus/content/groups/public/org/xwiki/platform/xwiki-platform-distribution-war/${VERSION}/xwiki-platform-distribution-war-${VERSION}.war && sha256sum xwiki-platform-distribution-war-${VERSION}.war && rm xwiki-platform-distribution-war-${VERSION}.war
-
On Mac, use the following one-liner and replace the value of the
VERSION
variable accordingly:VERSION="12.10.10"; wget http://nexus.xwiki.org/nexus/content/groups/public/org/xwiki/platform/xwiki-platform-distribution-war/${VERSION}/xwiki-platform-distribution-war-${VERSION}.war && shasum --algorithm 256 xwiki-platform-distribution-war-${VERSION}.war && rm xwiki-platform-distribution-war-${VERSION}.war
-
-
Execute the Gradle build (run
./gradlew
) to generate the various Dockerfiles and other resources for all image tags -
Test the docker container
-
If all is ok commit, push and close the jira issue created above
-
Note down the SHA1 of the last commit and update the official library file with it by creating a Pull Request (you can edit directly on the GitHub web page and create a Pull Request).
-
Make sure to update this file if the documentation needs to be updated.
Test the modified files. On Linux, you need to use sudo
on each docker command or configure it differently.
-
First time only: Install Docker. For Mac you can use the Docker for Mac installer.
- Make sure you open Docker before running the commands.
- Linux (except Ubuntu):
sudo systemctl start docker
- Linux (except Ubuntu):
- Make sure you open Docker before running the commands.
-
Create a network:
docker network create -d bridge xwiki-test
-
Make sure that
/tmp/xwiki-docker-test/postgres
and/tmp/xwiki-docker-test/xwiki
exist (you can run the clean up script below to create them) -
Update the PostgreSQL image to use the latest version:
docker pull postgres:latest
-
Execute the following command to start a Postgres database (for example):
docker run --net=xwiki-test --name postgres-xwiki-test -v /tmp/xwiki-docker-test/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:latest
-
Navigate to the directory to test, e.g.
14/postgres-tomcat
and issue:-
Update the Tomcat image to use the latest version:
docker pull <image name here>
, where the image name is found in theFROM
command inside the Dockerfile -
Build the image:
docker build -t xwiki-test .
-
Start XWiki (using the started Postgres container in this example):
docker run --net=xwiki-test --name xwiki-test -p 8080:8080 -v /tmp/xwiki-docker-test/xwiki:/usr/local/xwiki -e DB_USER=xwiki -e DB_PASSWORD=xwiki -e DB_DATABASE=xwiki -e DB_HOST=postgres-xwiki-test xwiki-test
Note that same as for the Postgres container above you'll need to remove the container if it already exists.
- In case you had an XWiki instance running on 8080 and the above command fails (i.e. address already in use), you cannot simply run it again. If you do (and you should try, actually), will try to recreate the container with the
xwiki-test
name that is now already in use by a container for which you are given the ID (note that down). Instead, you need to simply start the mentioned container ID which previously failed by runningdocker start <FAILED_START_CONTAINER_ID>
. - Open your browser to http://localhost:8080 and try to setup XWiki and verify it works
-
-
If all is ok commit, push and close the JIRA issue created above
Execute:
docker stop xwiki-test
docker rm xwiki-test
docker stop postgres-xwiki-test
docker rm postgres-xwiki-test
docker network rm xwiki-test
docker rmi xwiki-test
rm -Rf /tmp/xwiki-docker-test
mkdir -p /tmp/xwiki-docker-test/postgres
mkdir -p /tmp/xwiki-docker-test/xwiki
XWiki is licensed under the LGPL 2.1.
The Dockerfile repository is also licensed under the LGPL 2.1.
- If you wish to raise an issue or an idea of improvement use XWiki Docker JIRA project
- If you have questions, use the XWiki Users Mailing List/Forum or use the XWiki IRC channel
- If you wish to help out on the code, please send Pull Requests on XWiki Docker GitHub project
- Note that changes need to be merged to all other branches where they make sense and if they make sense for existing tags, those tags must be deleted and recreated.
- In addition, whenever a branch or tag is modified, a Pull Request on the DockerHub XWiki official image must be made
- Originally created by Vincent Massol
- Contributions from Fabio Mancinelli, Ludovic Dubost, Jean Simard, Denis Germain and a lot of others
- Some code was copied from https://github.com/ThomasSteinbach/docker_xwiki. Thank you Thomas Steinbach
- Stolen XWiki ascii art from https://github.com/babelop, see https://hub.docker.com/r/binarybabel/xwiki/~/dockerfile/