docker-image for docToolchain

Note: these docs might be outdated. The docToolchain docker image is mainly used together with the docToolchain-wrapper dtcw as explained in this tutotial: https://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/010_Install.html

sources and issue tracker: https://github.com/docToolchain/docker-image docker hub: https://hub.docker.com/r/doctoolchain/doctoolchain/tags

version will be updated with each release of: https://github.com/docToolchain/doctoolchain.github.io/blob/master/dtcw#L12

NOTE: Most of the following currently works only for jenkins-ssh-agent!

Set respective build environment

Align this with your personal settings/preferences.

: ${DOCKERHUB_USERNAME:="doctoolchain"}
: ${DTC_VERSION:="v2.2.1"}
# Export is not necessary as long as these variables are only used for local shell calls

Build Docker image(s)

docker build \
  -t ${DOCKERHUB_USERNAME}/doctoolchain-jenkins-ssh-agent:${DTC_VERSION} \
  --build-arg DTC_VERSION=${DTC_VERSION} \
  jenkins-ssh-agent

Test Docker image(s)

Note: This is only a smoke test (more elaborated test cases should be provided in the future).

docker run \
  --rm \
  -v ${PWD}/test:/workspace \
  -w /workspace \
  ${DOCKERHUB_USERNAME}/doctoolchain-jenkins-ssh-agent:${DCT_VERSION} \
  doctoolchain . tasks

how to use

create a bash script within the root of your project like this one:

doctoolchain.sh

#!/usr/bin/env bash
docker run --rm -it --entrypoint /bin/bash -v ${PWD}:/project doctoolchain/doctoolchain:v2.2.1 \
-c "doctoolchain . $1 $2 $3 $4 $5 $6 $7 $8 $9 -PinputPath=src/main/asciidoc -PmainConfigFile=config/docToolchain.groovy && exit"

As you can see, this command will pull the container, run it, mount your project folder and execute docToolchain.

You can overrride the docToolchain version to use and some parameters like the location of the config file.

With this script, you use docToolchain on your project like this:

./doctoolchain.sh generateHTML

Windows

on windows, the following batch script does the same:

docker run --rm --entrypoint /bin/bash -it -v %cd%:/project doctoolchain/doctoolchain:v2.2.1 -c "doctoolchain . %1 %2 %3 %4 %5 %6 %7 %8 %9 -PinputPath=src/main/asciidoc -PmainConfigFile=config/docToolchain.groovy && exit"

Available doctoolchain-images

The following list shows all official doctoolchain-docker-images and the typical usecases.

• https://hub.docker.com/r/doctoolchain/doctoolchain - Default doctoolchain-docker-image. Contains minimal useable doctoolchain installation. Should be good enough for most usecases.
• https://hub.docker.com/r/doctoolchain/doctoolchain-azure-devops-pipeline -
• https://hub.docker.com/r/doctoolchain/doctoolchain-jenkins-ssh-agent -
• https://hub.docker.com/r/doctoolchain/doctoolchain-with-pandoc - Contains a doctoolchain installation and a pandoc installation. Use this image if the doctoolchain-tasks you need, require pandoc. e.g. http://doctoolchain.org/docToolchain/v2.0.x/015_tasks/03_task_convertToDocx.html

Development / Deployment

New builds of the image are automatically triggered when (this repository is changed | a new Tag is created). The resulting docker image is then available through the docker hub.

Set up Github Actions for Continuous Integration

In order to automatically build and push new images via Github Actions the following steps are necessary.

• Activate Github Actions for your repository
• Create secrets for your repository
  • DOCKERHUB_USERNAME: Your Docker Hub username (or of your organization), e.g., doctoolchain.
  • DOCKERHUB_TOKEN: Caution: Do not store your password here but generate a suitable token (Read/Write should be sufficient).