Why use Docker?

Docker is a tool designed to make it easier to create, deploy and run applications by using containers. Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and ship it all out as one package. By doing so, thanks to the container, the developer can rest assured that the application will run on any other machine regardless of any customized settings that machine might have that could differ from the machine used for writing and testing the code.
Docker can easily be defined as the new standard in virtualization and cloud computing. Its mission is to smoothly package and ship code. That reduces the friction between developers that want to see their code working and SysAdmins. It's fast, easy to use and a developer-centric DevOps-ish tool. The Docker project homepage provides documentation on how to install Docker on your machine.

Getting started with XWiki in Docker

The XWiki open source community has published the first version of a production-ready XWiki system running in Docker in 2017. The user adoption has been increasing steadily, as now more than 26% of all XWiki active installs are represented by Docker installs.
The complete guide to install XWiki in Docker is available on <https://hub.docker.com/_/xwiki>. The easiest way to get started with XWiki in Docker is to use existing images (from DockerHub or built from the sources).

image:dockerhub-xwiki.png

Next, you can use the docker run command and follow three basic steps to run a container for the XWiki image and one for the database image to which XWiki connects to.

Step 1: Create a dedicated docker network

Use the docker network command to create a network bridge to be used next by the images.

``
docker network create -d bridge xwiki-nw
``

Step 2: Run a container for the database image to which XWiki connects to

When installing XWiki with MySQL you need to first create a file init.sql inside a folder my/path/mysql-init which will give permissions for the xwiki user to create new schemas (required to be able to create sub-wikis):

``
grant all privileges on . to xwiki@'%' identified by 'xwiki'
``

Here’s how the docker run command looks like to set up the MySQL database:

``
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=utf8 --collation-server=utf8_bin --explicit-defaults-for-timestamp=1
``

Parameters explained:

  • xwiki-nw is the network bridge created at step 1
  • mysql-xwiki is the name of the database docker container
  • /my/path/mysql is the local folder where docker will store the database data
  • /my/path/mysql-init is the local folder to store the file init.sql (the folder needs to be on your filesystem, you can use any name for either folder or file)
  • The MySQL image v5.7 is pulled from Docker Hub
  • MYSQL_DATABASE specifies the name of the database for XWiki.

Step 3: Run one container for the XWiki image

Next, use the docker run command for the XWiki image~:

``
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
``

Parameters explained:

  • xwiki-nw is the network bridge created at step 1,
  • xwiki is the name of the XWiki docker container,
  • -p 8080:8080 exposes the container's 8080 port to the host 8080 (-p hostPort:containerPort),
  • for -v /my/path/xwiki:/usr/local/xwiki, the path /my/path/xwiki represents the local folder where docker will store configuration files and dynamic data for XWiki, while /usr/local/xwiki represents the path to store data inside the container,
  • DB_HOST is the name of the container holding the database created at step 2.

How to test it’s actually working?

If you open the browser and you check your wiki (e.g. <http://localhost:8080/bin/view/Main/>), you should get the Distribution Wizard from XWiki to finish the installation process:

image:XWiki-up.png

You can connect to the MySQL instance inside the mysql-xwiki container:

``
docker exec -it mysql-xwiki bash
mysql -uxwiki -pxwiki
``

Next, you can use standard MySQL commands to check the database created by XWiki.

Things to have in mind when installing XWiki with Docker

  • The local folder where docker stores the data /my/path/mysql needs to be empty.
  • All local folders (e.g. /my/path/mysql-init, /my/path/mysql, /my/path/xwiki) need proper rights provided by the OS.
  • Use docker ps to check if the containers are correctly up and running.
  • Take a look at the complete documentation on <https://github.com/xwiki-contrib/docker-xwiki/blob/master/README.md>.

General FAQ

How to update the wiki when using the Docker installation?

You can take a look at the following guides for upgrades:

  • https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Upgrade#HMethod1.BUpgradingfromDocker.Docker
  • https://github.com/xwiki-contrib/docker-xwiki/blob/master/README.md#upgrading-xwiki

How to install a text editor inside the XWiki Docker image?

The image is very small, so you won’t have many tools. You can easily install them with an apt-get command:

``
apt-get update && apt-get install vi
``

Is there a step by step video tutorial about installing XWiki with Docker?

The XWiki community has created a video including a step by step installation of XWiki using Docker: https://www.youtube.com/watch?v=4bNkU3qbrHA

I get a "ERROR c.x.x.s.DBCPConnectionProvider - Could not create a DBCP pool" error when trying to complete the installation. How can I fix it?

You might encounter this error if you copy the docker command to setup the MySQL container as is mentioned in Step 3. To fix it use an existing local path for MySQL, e.g.

``
"~/Downloads/dockertests/mysql"
``

.

Here is what it would look like in an example

``
docker run --net=xwiki-nw --name mysql-xwiki -v ~/Downloads/dockertests/mysql:/var/lib/mysql -v ~/Downloads/dockertests/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=utf8 --collation-server=utf8_bin --explicit-defaults-for-timestamp=1
``

.