Installing plug-ins in a Docker image

To install custom plug-ins or make other changes based on the DITA-OT parent image, you can create your own Dockerfile and specify the official DITA-OT image as the basis for your image.

About this task

Each subsequent declaration in the Dockerfile modifies this parent image, so you can start with the official image, and add custom plug-ins or other commands as required to create a custom Docker image that includes everything you need to publish your content.

Procedure

  1. Create a new Dockerfile and specify the official DITA-OT image in the FROM directive. 
    # Use the latest DITA-OT image ↓ as parent:
FROM ghcr.io/dita-ot/dita-ot:4.2.3
  2. Optional: You can extend your image with a RUN declaration that runs the dita command from the container to install a custom plug-in, and specify the filename or URL of the plug-in’s distribution ZIP file. 
    # Install a custom plug-in from a remote location:
RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip
  3. Optional: You can also install custom plug-ins from the main DITA-OT plug-in registry at dita-ot.org/plugins, or from your company plug-in registry. 
    # Install from the registry at dita-ot.org/plugins:
RUN dita --install org.dita-community.pdf-page-break

Example

The docsrc/samples folder in the DITA-OT installation directory contains a complete example:

Figure 1. Sample Dockerfile with custom plug-ins: dita-ot-dir/docsrc/samples/docker/Dockerfile
# Use the latest DITA-OT image ↓ as parent:
FROM ghcr.io/dita-ot/dita-ot:4.2.3

# Install a custom plug-in from a remote location:
RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip

# Install from the registry at dita-ot.org/plugins:
RUN dita --install org.dita-community.pdf-page-break

Building a new image

You can build a Docker image from this example by running the following command from the dita-ot-dir/docsrc/samples directory:

$ docker image build -t sample-docker-image:1.0 docker/
[+] Building 81.5s (4/6)                                                                                                                                                           
 => [internal] load build definition from Dockerfile                                                                                                                          0.0s
 => => transferring dockerfile: 367B                                                                                                                                          0.0s
 => [internal] load .dockerignore                                                                                                                                             0.0s
 => => transferring context: 2B                                                                                                                                               0.0s
 => [internal] load metadata for ghcr.io/dita-ot/dita-ot:4.2.3
 => [1/3] FROM ghcr.io/dita-ot/dita-ot:4.2.3@sha256:<hash>
 => => resolve ghcr.io/dita-ot/dita-ot:4.2.3@sha256:<hash>
Step 2/3 : RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip
 ---> Running in d510f874cae0
Added net.infotexture.dita-bootstrap
Removing intermediate container d510f874cae0
 ---> 63deb8e15b5b
Step 3/3 : RUN dita --install org.dita-community.pdf-page-break
 ---> Running in b4ef2fcad916
Added org.dita-community.pdf-page-break
Removing intermediate container b4ef2fcad916
 ---> 402885636b7f
Successfully built 402885636b7f
Successfully tagged sample-docker-image:1.0

Docker steps through each instruction in the Dockerfile to build the sample image. In this case, the dita command provides feedback on each installed plug-in.

Running the new container

You can then start a container based on your new image:

$ docker container run --rm \
  -v /path/to/dita-ot-dir/docsrc:/src sample-docker-image:1.0 \
  -i /src/userguide.ditamap \
  -o /src/out/dita-bootstrap \
  -f html5-bootstrap -v
This command sequence specifies the following options:
  • -v mounts the docsrc subfolder of the DITA-OT directory on your host machine and binds it to the /src volume in the container
  • -i specifies dita-ot-dir/docsrc/userguide.ditamap as the input map file
  • -o writes the output to dita-ot-dir/docsrc/out/dita-bootstrap
  • -f sets the output format to the Bootstrap template, and
  • -v displays build progress messages with verbose logging

When the build is finished, you should find a copy of the DITA-OT documentation under dita-ot-dir/docsrc/out/dita-bootstrap, styled with the basic Bootstrap template from the custom plug-in.