se/SE/schema/WPS_Functions/dita-ot/dita-ot-3.5/docsrc/topics/creating-docker-images.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->

<task id="ID">
  <title>Installing plug-ins in a Docker image</title>
  <titlealts>
    <navtitle>Custom images</navtitle>
  </titlealts>
  <shortdesc>To install custom plug-ins or make other changes based on the DITA-OT parent image, you can create your own
      <filepath>Dockerfile</filepath> and specify the official DITA-OT image as the basis for your image. </shortdesc>
  <prolog>
    <metadata>
      <keywords>
        <indexterm>plug-ins
          <indexterm>installing in Docker images</indexterm></indexterm>
        <indexterm>Docker images</indexterm>
      </keywords>
    </metadata>
  </prolog>
  <taskbody>
    <context>
      <p>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.</p></context>
    <steps>
      <step>
        <cmd>Create a new <filepath>Dockerfile</filepath> and specify the official DITA-OT image in the
            <filepath>FROM</filepath> directive.</cmd>
        <stepxmp>
          <codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef href="../samples/docker/Dockerfile#line-range(1,2)"/></codeblock>
        </stepxmp>
      </step>
      <step importance="optional">
        <cmd>You can extend your image with a <codeph>RUN</codeph> declaration that runs the <cmdname>dita</cmdname>
          command from the container to install a custom plug-in, and specify the filename or URL of the plug-in’s
          distribution ZIP file.</cmd>
        <stepxmp>
          <codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef href="../samples/docker/Dockerfile#line-range(4,5)"/></codeblock>
        </stepxmp>
      </step>
      <step importance="optional">
        <cmd>You can also install custom plug-ins from the main DITA-OT plug-in registry at
          <xref keyref="site-plugin-registry"/>, or from your company plug-in registry.</cmd>
        <stepxmp>
          <codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef href="../samples/docker/Dockerfile#line-range(7,8)"/></codeblock>
        </stepxmp>
      </step>
    </steps>
    <example>
      <p>The <filepath>docsrc/samples</filepath> folder in the DITA-OT installation directory contains a complete
        example:</p>
      <fig>
        <title>Sample Dockerfile with custom plug-ins: <filepath conkeyref="conref-task/samples-dir"
            /><filepath>/docker/Dockerfile</filepath></title>
        <codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef href="../samples/docker/Dockerfile"/></codeblock>
      </fig>
    </example>
    <example>
      <title>Building a new image</title>
      <p>You can build a Docker image from this example by running the following command from the <filepath
          conkeyref="conref-task/samples-dir"/> directory:</p>
      <codeblock>$ <cmdname>docker</cmdname> image build -t sample-docker-image:1.0 .
Sending build context to Docker daemon  2.048kB
Step 1/3 : FROM docker.pkg.github.com/dita-ot/dita-ot/dita-ot:<keyword keyref="maintenance-version"/>
 ---> 9abb96827538
Step 2/3 : RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/3.3.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
</codeblock>
      <p>Docker steps through each instruction in the Dockerfile to build the sample image. In this case, the
          <cmdname>dita</cmdname> command provides feedback on each installed plug-in.</p>
    </example>
    <example>
      <title>Running the new container</title>
      <p>You can then start a container based on your new image:</p>
      <codeblock>$ <cmdname>docker</cmdname> container run -it \
  -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</codeblock>
      <p>This command sequence specifies the following options:
        <ul>
          <li><option>-v</option> mounts the <filepath>docsrc</filepath> subfolder of the DITA-OT directory on your host
            machine and binds it to the <filepath>/src</filepath> volume in the container</li>
          <li><option>-i</option> specifies <filepath conkeyref="conref-task/docsrc-dir"
              /><filepath>/userguide.ditamap</filepath> as the input map file</li>
          <li><option>-o</option> writes the output to <filepath conkeyref="conref-task/docsrc-dir"
              /><filepath>/out/dita-bootstrap</filepath></li>
          <li><option>-f</option> sets the output format to the Bootstrap template, and</li>
          <li><option>-v</option> displays build progress messages with verbose logging</li>
        </ul>
      </p>
      <p>When the build is finished, you should find a copy of the DITA-OT documentation under <filepath
          conkeyref="conref-task/docsrc-dir"/><filepath>/out/dita-bootstrap</filepath>, styled with the basic Bootstrap
        template from the custom plug-in.</p>
    </example>
  </taskbody>
</task>