Creating Your Own DITA Open Toolkit Containers

You can easily configure your own DITA Open Toolkit containers using the ditaot/dita-ot-base container as a starting point.

The ditaot/dita-ot container is suitable for direct use in running the Open Toolkit but, because it exposes the DITA-OT directory as a volume, is not usable as the base container for new Open Toolkit containers. This is because once you declare a directory as a volume in a Docker file, any subsequent changes to that directory made by the Docker file will not be persisted in the final image.

The ditaot/dita-ot-base container is designed to be used as the base for new DITA OT containers by not defining the DITA-OT volume. The base Dockerfile is available on GitHub in the https://github.com/dita-community/dita-community-ot-docker project as dita-ot-base/Dockerfile.

You set up your own working container using a Dockerfile like this:

FROM ditaot/dita-ot-base
MAINTAINER Me Myself "me@example.com"
#
# My custom DITA Open Toolkit
#
#
# Add your additional stuff here
#
VOLUME /opt/dita-ot/DITA-OT
VOLUME /opt/dita-ot/data
CMD /bin/bash
#
# End of Dockerfile
#

The FROM statement is required and must be the first statement in the file. The MAINTAINER statement is documentation.

The VOLUME statement makes the /opt/dita-ot/DITA-OT directory in the container available to other containers that use this container's volumes. It should always be /opt/dita-ot/DITA-OT so you can use your own container in place of the base DITA OT container without affecting any containers that use the OT from a container.

There are basically two ways to add your custom plugins to the container:

Get a Zip file from the Web using wget or curl via the Dockerfile RUN statement. For example, if your plugins are in a GitHub repository you can get the plugin as a Zip file using an HTTP URL.
Copy files from the host machine into the container using the Dockerfile ADD statement.

To get a Zip file use wget like so:

FROM ditaot/dita-ot-base
MAINTAINER Me Myself "me@example.com"
#
# My custom DITA Open Toolkit
#
WORKDIR ${DITA_HOME}
ENV DITA_COMM_URL=https://github.com/dita-community/ BRANCH=develop
#
# Get plugin from DITA Community project:
RUN wget ${DITA_COMM_URL}org.dita-community.common.xslt/archive/${BRANCH}.zip && \
  unzip ${BRANCH}.zip -d plugins && 
  rm ${BRANCH}.zip
#
# Integrate new plugins
#
RUN ant -f integrator.xml
#
VOLUME /opt/dita-ot/DITA-OT
CMD /bin/bash
#
# End of Dockerfile
#

The WORKDIR statement sets the current working directory to the DITA-OT directory. You can refer to environment variables set in the base container's Dockerfile.

The ENV statement defines two new environment variables that make it easier to construct the wget commands that follow. For the DITA Community project, the latest code is normally on the develop branch.

The RUN wget statement runs a Linux command. In this case the command is actually three commands, wget, unzip, and rm, connected by "&&" (boolean and) operators. This is normal Linux shell script syntax. It means "do the first command and, if it succeeds, perform the next command, and then the next.

Stringing commands together like this is best Docker practice as it avoids creating unnecessary layers in the container and avoids some issues with caching.

The RUN ant statement runs the normal Open Toolkit integrator script to integrate the new plugins.

The VOLUME statement publishes the DITA-OT directory as a volume, making it available to other containers. This statement must follow the commands that add things to the DITA-OT directory.

The CMD statement defines the default command to run when the container is started, in this case a bash shell. If you run the container without the -it parameters the shell will run and then immediately exit. If you specify the -it parameters to the docker run command then you will end up in a bash terminal window inside the container. If you specify a command as a parameter to the docker run command then it is run in place of the command defined on the CMD statement.

It should be clear that you can quickly copy and paste the RUN wget lines to add whatever HTTP-accessible plugins you want.

Note also that using the 2.x version of the Open Toolkit you could use the dita --install command to directly install plugins from Zip files via HTTP URL. However, if you need your container to work with both the 1.x and 2.x Open Toolkit versions you need to use the wget plus integrator.xml approach.

To use plugins that are on your local machine you can use the Dockerfile ADD statement, which copies files from the host machine into the container. The main requirement is that the files to be added must be in or under the directory that contains the Dockerfile file:

FROM ditaot/dita-ot-base
MAINTAINER Me Myself "me@example.com"
#
# My custom DITA Open Toolkit
#
WORKDIR ${DITA_HOME}
ENV DITA_COMM_URL=https://github.com/dita-community/ BRANCH=develop
#
# Add my plugin:
ADD plugins/org.example.myhtml/ .
#
# Integrate new plugins
#
RUN ant -f integrator.xml
#
VOLUME /opt/dita-ot/DITA-OT
CMD /bin/bash
#
# End of Dockerfile
#

To build the container you use the docker build command from the directory that contains the Dockerfile file:

$ cd /workspace/mycontainer/dita-ot
$ ls
Dockerfile
plugins/
$ docker build .
 {lots of messages} ...
Removing intermediate container 5185b8770fc4
Successfully built 3df126334196
$ _

If you don't specify an image name with the -t parameter then the build command will assign a numeric image ID . You can run the container by specifying the numeric ID:

$ docker run -it 3df126334196
root@a90236ed0684:~/DITA-OT# _

You can get a list of all the images in your environment using the docker images command:

$ docker images
docker images
REPOSITORY                          TAG                 IMAGE ID            CREATED             SIZE
<none>                              <none>              3df126334196        2 minutes ago       778.7 MB
… {potentially long list of images}
$ _

You can remove images using the docker rmi command:

$ docker rmi -f 3df126334196
Deleted: sha256:3df1263341965178e0b43215fb2087c42ae7c815f4f636810531a7660055bb53
Deleted: sha256:fb433121937830f727d2218af86bca050af86ea7e21b713cfb4b1abea060e1a1
$ _

The -f (force) parameter forces removal of the image. If you don't force the removal you have to first rm the container image, which will be stopped if you ran it before.

You can use the --rm parameter of the docker run command to have the image automatically remove itself after it runs:

docker run --rm -it 3df126334196
root@a90236ed0684:~/DITA-OT# _

To give the image a name, use the -t (tag) parameter of the docker build command:

$ docker build -t me/dita-ot .
 {lots of messages, but fewer than before 
  if there was no change to the Dockerfile}...
$ docker images
docker images
REPOSITORY                          TAG                 IMAGE ID            CREATED             SIZE
me/dita-ot                          latest              1e5c40fd12af        24 seconds ago      778.7 MB
...
$ _

Now you can run the image using the tag rather than the image ID:

$ docker run --rm -it me/dita-ot
root@8b64266207fd:~/DITA-OT#