# 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.