JSPWiki for Docker#

JSPWiki can be used with Docker. Docker images can be built from source or you can use a pre-built official image.

Default Image#

The default JSPWiki Docker image uses the official Docker Community supported Apache Tomcat 9 image which is based on the OpenJDK 11 built on Debian Buster.

JSPWiki is built from source using Apache Maven during the image build process.

Prerequisites#

To use the pre-built image or build one from source you only need a Docker Engine. See the installation instructions on the docker site for details.

Using the Pre-Built Image#

To download it locally from the docker hub.

Get the Image#

$ docker pull apache/jspwiki

Running the Container#

$ docker run -d -p 8080:8080 --name jspwiki apache/jspwiki

This means :

• -d - detached mode, run the container in the background
• -p 8080:8080 - bind the host port (8080) to the container port (8080). JSPWiki always runs on port 8080 inside the container.
• --name jspwiki - the new docker container will get the name jspwiki (instead of a generated container name)
• apache/jspwiki - the name of the image to run

Building from Source#

Building the Image#

From the source root directory that contains the Dockerfile. The example uses a $version variable because the version is referred to multiple times. It is optional and can be replaced by any version number you would like to use. If you do not specify a version with the tag name it will default to latest.

Watch out for the space and period at the end which means the current directory.

$ version='2.11.0'
$ docker build --tag="jspwiki:$version" .

Running the Container#

This is exactly like running the pre-built image except for the image name:version at the end.

$ docker run -d -p 8080:8080 --name jspwiki jspwiki:$version

Check the Results#

Just point your browser at http://localhost:8080/, that should give you a working wiki right away!

To see the list of running containers use docker ps or docker container ls and docker ps -a or docker container ls -a will show all containers running and stopped.

$ docker ps
CONTAINER ID        IMAGE                   COMMAND                 CREATED             STATUS        PORTS                    NAMES
5f0f5b0b5996        apache/jspwiki          "/usr/local/tomcat/bi"   4 minutes ago       Up 4 minutes 0.0.0.0:8080->8080/tcp   jspwiki

You can also execute commands inside the jspwiki container with the docker exec command and, for example, look at the last 5 lines in /var/jspwiki/logs/jspwiki.log:

$ docker exec -ti jspwiki tail -5 /var/jspwiki/logs/jspwiki.log
2016-03-28 09:34:35,070 [localhost-startStop-1] INFO org.apache.wiki.util.UtilJ2eeCompat  - apache tomcat detected
2016-03-28 09:34:35,073 [localhost-startStop-1] INFO org.apache.wiki.ajax.WikiAjaxDispatcherServlet  - WikiAjaxDispatcherServlet initialized.
2016-03-28 09:34:35,075 [localhost-startStop-1] INFO org.apache.wiki.WikiServlet  - WikiServlet initialized.
2016-03-28 09:34:38,054 [http-nio-8080-exec-1] INFO org.apache.wiki.util.PropertyReader JSPWiki:/JSPWiki:http://localhost:8080/ - No jspwiki.custom.config defined for this context, looking for custom properties file with default name of: /jspwiki-custom.properties
2016-03-28 09:34:38,057 [http-nio-8080-exec-1] INFO org.apache.wiki.util.PropertyReader JSPWiki:/JSPWiki:http://localhost:8080/ - No custom property file found, relying on JSPWiki defaults.

Stopping and Starting the Container#

To stop the container, simply issue the docker stop or docker container stop command against the containerid (or container name if you gave it a name during first run).

$ docker ps
CONTAINER ID    IMAGE                 COMMAND                  CREATED            STATUS PORTS                    NAMES
5f0f5b0b5996    apache/jspwiki        "/usr/local/tomcat/bi"   6 minutes ago      Up 6 minutes 0.0.0.0:8080->8080/tcp   jspwiki
$ docker stop jspwiki
jspwiki
$ docker ps
CONTAINER ID    IMAGE                 COMMAND                  CREATED            STATUS              PORTS               NAMES
$ docker ps -a
CONTAINER ID    IMAGE                 COMMAND                  CREATED            STATUS              PORTS               NAMES
5f0f5b0b5996    apache/jspwiki        "/usr/local/tomcat/bi"   6 minutes ago      Exited (143) 4 seconds ago              jspwiki

You can restart it with the docker start or docker container start command, you have to find the containerid with the docker ps -a command first , (or simply use the container name if you gave the container a name during first run):

$ docker start jspwiki
jspwiki
$ docker ps
CONTAINER ID        IMAGE                  COMMAND                  CREATED             STATUS       PORTS                    NAMES
5f0f5b0b5996        apache/jspwiki         "/usr/local/tomcat/bi"   7 minutes ago       Up 5 seconds 0.0.0.0:8080->8080/tcp   jspwiki

As you will notice, after a stop/start you still have the data (pages) that were created after the first container start. (you can check easily with the Recent Changes page)

Removing the Container#

If you want to get rid of the container (and all of the data in it!) you first should stop it, then you can remove it with the docker rm or docker container rm command (or use docker rm -f to forcibly remove it right away):

$ docker ps
CONTAINER ID        IMAGE                  COMMAND                  CREATED            STATUS            PORTS                    NAMES
5f0f5b0b5996        apache/jspwiki         "/usr/local/tomcat/bi"   9 minutes ago      Up About a minute 0.0.0.0:8080->8080/tcp   jspwiki
$ docker stop jspwiki
jspwiki
$ docker ps -a
CONTAINER ID        IMAGE                  COMMAND                  CREATED            STATUS            PORTS               NAMES
5f0f5b0b5996        apache/jspwiki         "/usr/local/tomcat/bi"   9 minutes ago      Exited (143) 6 seconds ago            jspwiki
$ docker rm jspwiki
jspwiki
$ docker ps -a
CONTAINER ID        IMAGE                  COMMAND                  CREATED            STATUS            PORTS               NAMES

Note that all your data is lost when you remove the container. (You can keep data apart using Docker Volumes, see next paragraph)

ENV variables#

Docker's Environment variables will be passed to the running instance of JSPWiki inside the container, which is able to translate them to something that JSPWiki will understand, i.e., ENV jspwiki_use_external_logconfig true will be understood by the WikiEngine as jspwiki.use.external.logconfig=true, ENV jspwiki_pageProvider VersioningFileProvider as jspwiki.pageProvider VersioningFileProvider, and so on.

Persisting Data#

If you use docker to run JSPWiki only for quick test purposes, you probably are not interested in keeping the data (created/changed pages, registered users, logfiles).
But you can also run a JSPWiki docker container in production-like environments where you want to keep your data even after you removed a container.
As an example you might sometimes want to run a newer version of your JSPWiki Docker container.

Seeding the Volume Directory#

To begin with the default pages you can copy them from the source tree into a host OS directory used to persist the data.

$ cp ./jspwiki-wikipages/en/src/main/resources/* <path-to-your>/jspwiki-pages/

Running with a Volume#

To use the data outside of the container, you can use the --volume switch when you startup the container :

$ docker run -d -p 8080:8080 --env="jspwiki_baseURL=http://localhost/" --name jspwiki_8080 --volume="<path-to-your>/jspwiki-pages:/var/jspwiki/pages" apache/jspwiki 
240232ebb32e58dee7ad95471128210f71007bbeb11735ffd5394113959ace75

This way you will get your pages in a directory on the host OS in <path-to-your>/jspwiki-pages. You can use the same technique to store the attachments, the log files, the jspwiki-custom.properties file, etc.

jspwiki.policy + userdatabase.xml (wiki-users) + server.xml

$ docker container ls
CONTAINER ID   IMAGE            COMMAND                  CREATED      STATUS       PORTS                                       NAMES
64560e4e56c2   apache/jspwiki   "/usr/local/tomcat/b…"   5 days ago   Up 6 hours   0.0.0.0:8080->8080/tcp, :::8080->8080/tcp   jspwiki_8080

$ docker exec -it jspwiki_8080 /bin/bash
root@64560e4e56c2:/usr/local/tomcat# 

root@64560e4e56c2:/usr/local/tomcat/webapps/ROOT/WEB-INF# ls -l
-rw-r--r-- 1 root root  5713 Nov  3 10:53 jspwiki.policy

root@64560e4e56c2:/var/jspwiki/etc# ls -l
-rw-r--r-- 1 root root 881 Nov  3 10:53 groupdatabase.xml
-rw-r--r-- 1 root root 877 Nov  3 10:53 userdatabase.xml

root@64560e4e56c2:/usr/local/tomcat/conf# ls -l
-rw-r--r-- 1 root root   7589 Nov 10 08:26 server.xml

Running Multiple Instances#

You can run multiple instances of the image of course. You only have to make sure they use different TCP ports.
So for example starting 5 containers (with also a limit on memory usage added) :

$ for PORT in `seq 9080 9084`; do docker run -d -p ${PORT}:8080 --memory=128m --env="jspwiki_baseURL=http://localhost:${PORT}/" --name jspwiki-${PORT} metskem/docker-jspwiki; done
68481eed8d609ac91711a78bd80505b398a8a37c9cc435e44eb0b2b7f881444b
b3b967dc4fe721d5efce65959bfd5b4fa6061e053b3fd7b6d814bfc68a0a5261
6a23a3ac3df9aaf1a7f2dda96b6a535d58d06a429f458edaa4101ec89a6416e1
b55b716ed49ff6ca6ba581794fe4ba5bde0439e10301f78acb62d5dec1118304
73d4cd8f29a072884a965ad3a86a5d090762fc046fe424c7b842b1c0b3a72122
$ docker ps
CONTAINER ID        IMAGE                    COMMAND                CREATED             STATUS       PORTS                    NAMES
73d4cd8f29a0        apache/jspwiki           "/bin/sh -c '/usr/lo   4 seconds ago       Up 3 seconds 0.0.0.0:9084->8080/tcp   jspwiki-9084
b55b716ed49f        apache/jspwiki           "/bin/sh -c '/usr/lo   4 seconds ago       Up 3 seconds 0.0.0.0:9083->8080/tcp   jspwiki-9083
6a23a3ac3df9        apache/jspwiki           "/bin/sh -c '/usr/lo   4 seconds ago       Up 3 seconds 0.0.0.0:9082->8080/tcp   jspwiki-9082
b3b967dc4fe7        apache/jspwiki           "/bin/sh -c '/usr/lo   5 seconds ago       Up 4 seconds 0.0.0.0:9081->8080/tcp   jspwiki-9081
68481eed8d60        apache/jspwiki           "/bin/sh -c '/usr/lo   5 seconds ago       Up 4 seconds 0.0.0.0:9080->8080/tcp   jspwiki-9080

And you can easily get rid of them too :

$ docker stop `docker ps -aq`
73d4cd8f29a0
b55b716ed49f
6a23a3ac3df9
b3b967dc4fe7
68481eed8d60
240232ebb32e
c8c73ddd9876
$ docker rm `docker ps -aq`
73d4cd8f29a0
b55b716ed49f
6a23a3ac3df9
b3b967dc4fe7
68481eed8d60
240232ebb32e
c8c73ddd9876
$ docker ps -a
CONTAINER ID        IMAGE                    COMMAND                CREATED             STATUS       PORTS                    NAMES

Customizing Your Image#

You can customize your build by making source code changes (not covered here) or change other things like the Tomcat base image version and platform OS and JDK version.

Example: Change the platform OS from Debian to the CentOS based variation Amazon Linux 2 that uses their Corretto JDK optimized to run in AWS. Edit the Dockerfile as follows:

Change the Maven image used for building JSPWiki to match the one for the OS. (Probably not need but done for consistency)

# FROM maven:3.8-jdk-8 as package
FROM maven:3.8-amazoncorretto-11 as package

Change the Tomcat base image

# FROM tomcat:9.0
FROM tomcat:9.0-jdk11-corretto

Replace some Debian specific lines with RedHat counterparts to add the unzip package.

# RUN set -x \
# && export DEBIAN_FRONTEND=noninteractive \
# && apt install --fix-missing --quiet --yes unzip
RUN yum -y install \
unzip

Add after the # install jspwiki section and before # make port visible in metadata

# remove unzip and cleanup
RUN yum -y remove \
unzip \
&& yum clean all

That's all... Enjoy!