using-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>Running the <cmdname>dita</cmdname> command from a Docker image</title>
  <titlealts>
    <navtitle>Using Docker images</navtitle>
  </titlealts>
  <shortdesc>
    <ph id="docker-desc">
      <xref keyref="docker"/> is a platform used to build, share, and run portable application containers. As of version
      3.4, the DITA-OT project provides an official Docker container image that includes everything you need to run the
      toolkit and publish DITA content from a containerized environment.</ph></shortdesc>
  <prolog>
    <metadata>
      <keywords>
        <indexterm><cmdname>dita</cmdname> command
          <indexterm>running from Docker images</indexterm></indexterm>
        <indexterm>Docker images</indexterm>
      </keywords>
    </metadata>
  </prolog>
  <taskbody>
    <section>
      <title>About application containers</title>
      <p>Using containers to deploy applications isolates software from its environment to ensure that it works
        consistently despite any differences in the host operating system, for example.</p>
      <p>Docker containers are designed as stateless machines that can be quickly created and destroyed, started and
        stopped. Each Docker image provides its own private filesystem that includes only the code required to run the
        application itself — it is not intended for persistent data storage.</p>
      <p>When a container is stopped, any changes made within the container are lost, so source files and generated
        output should be stored outside the container. These resources are attached to the container by mounting
        directories from the host machine.</p>
    </section>
    <prereq>
      <p>To run the DITA-OT image, you will need to install Docker and be able to access the GitHub Container Registry.
        <ul>
          <li>To download Docker Desktop, you may be prompted to sign in with your Docker ID (or sign up to create
            one).</li>
        </ul>
      </p>
    </prereq>
    <steps outputclass="multi-platform">
      <step>
        <cmd>Install Docker for your operating system.</cmd>
        <choices>
          <choice platform="windows">
            <xref href="https://docs.docker.com/desktop/windows/install/" format="html" scope="external">Install
              Docker Desktop on Windows</xref>
          </choice>
          <choice platform="mac">
            <xref href="https://docs.docker.com/desktop/mac/install/" format="html" scope="external">Install Docker
              Desktop on Mac</xref>
          </choice>
          <choice platform="mac">On macOS, you can also install Docker Desktop via
            <xref keyref="homebrew"/>:
            <codeblock outputclass="syntax-bash">$ <cmdname>brew</cmdname> install homebrew/cask/docker
<systemoutput>Downloading…</systemoutput></codeblock>
          </choice>
          <choice platform="mac windows">
            When you first run the Docker Desktop application, you may be prompted to grant privileged access to allow
            Docker to install its networking components and links to the Docker apps. Grant this access and accept the
            service agreement to proceed.
          </choice>
          <choice
            platform="linux"
          >On Linux, install Docker Community Edition (CE) via your operating system’s package manager, for
            example: <codeblock outputclass="syntax-bash">$ <cmdname
              >sudo</cmdname> apt-get install docker-ce</codeblock></choice>
        </choices>
      </step>
      <step>
        <cmd>To build output, map a host directory to a container volume and specify options for the
            <cmdname>dita</cmdname> command.</cmd>
        <stepxmp>
          <codeblock outputclass="syntax-bash">$ <cmdname>docker</cmdname> run -it \
  -v /Users/<varname>username</varname>/source:/src ghcr.io/dita-ot/dita-ot:<keyword keyref="maintenance-version"/> \
  -i /src/input.ditamap \
  -o /src/out \
  -f html5 -v</codeblock>
          <p>This command sequence specifies the following options:
            <ul>
              <li><option>-v</option> mounts the <filepath>source</filepath> subfolder of your home directory and binds
                it to the <filepath outputclass="preserve-separator">/src</filepath> volume in the container</li>
              <li><option>-i</option> specifies the <filepath>input.ditamap</filepath> file in your
                  <filepath>source</filepath> folder as the input map file</li>
              <li><option>-o</option> writes the output to <filepath>source/out</filepath></li>
              <li><option>-f</option> sets the output format to HTML5, and</li>
              <li><option>-v</option> displays build progress messages with verbose logging</li>
            </ul>
          </p>
          <div platform="windows">
            <p>On Windows, if your <filepath>Users</filepath> directory is on the <filepath>C:\</filepath> drive, use
              <filepath>/c/Users/…</filepath> to map the host directory:</p>
            <codeblock>> C:\Users\username> <cmdname>docker</cmdname> run -it ^
  -v /c/Users/<varname>username</varname>/source:/src ghcr.io/dita-ot/dita-ot:<keyword keyref="maintenance-version"/> ^
  -i /src/input.ditamap ^
  -o /src/out ^
  -f html5 -v</codeblock>
          </div>
        </stepxmp>
        <info>
          <note>The DITA-OT container image uses the <codeph>ENTRYPOINT</codeph> instruction to run the
              <cmdname>dita</cmdname> command from the <filepath
              outputclass="preserve-separator"
            >/opt/app/bin/</filepath> directory of the container
            automatically, so you there’s no need to include the <cmdname>dita</cmdname> command itself, only the
            arguments and options you need to publish your content.</note>
        </info>
      </step>
    </steps>
  </taskbody>
</task>