<commit_before><?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="projects-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 log in to the GitHub Package 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>
          <li>To retrieve docker images from the GitHub Package Registry, you will also need a GitHub account.</li>
        </ul></p>
    </prereq>
    <steps>
      <step>
        <cmd>Install Docker for your operating system.</cmd>
        <choices>
          <choice>
            <xref href="https://docs.docker.com/docker-for-windows/install/" scope="external" format="html">Install
              Docker Desktop on Windows</xref>
          </choice>
          <choice>
            <xref href="https://docs.docker.com/docker-for-mac/install" scope="external" format="html">Install Docker
              Desktop on Mac</xref>
          </choice>
          <choice>On macOS, you can also install Docker Desktop via
            <xref keyref="homebrew"/>:
            <codeblock>$ <cmdname>brew cask install docker</cmdname>
<systemoutput>Downloading…</systemoutput></codeblock>
          </choice>
          <choice>On Linux, install Docker Community Edition (CE) via your operating system’s package manager, for
            example: <codeblock>$ <cmdname>sudo</cmdname> apt-get install docker-ce</codeblock></choice>
        </choices>
      </step>
      <step>
        <cmd>Log in to the GitHub Package Registry.</cmd>
        <substeps>
          <substep>
            <cmd>In your
              <xref href="https://github.com/settings/tokens" format="html" scope="external">GitHub profile
                settings</xref>, create a new personal access token with the <codeph>read:packages</codeph> scope.</cmd>
            <info>For more information, see
              <xref href="https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line"
                scope="external" format="html">Creating a personal access token for the command line</xref>.</info>
          </substep>
          <substep>
            <cmd>On the command line, run the <cmdname>docker</cmdname> command to log in with your GitHub
              credentials.</cmd>
            <stepxmp>
              <codeblock><cmdname>docker</cmdname> login docker.pkg.github.com -u <varname>USERNAME</varname> -p <varname>PASSWORD/TOKEN</varname></codeblock>
            </stepxmp>
            <info>For more information, see
              <xref
                href="https://help.github.com/en/articles/configuring-docker-for-use-with-github-package-registry#authenticating-to-github-package-registry"
                scope="external" format="html">Authenticating to GitHub Package Registry</xref>.</info>
          </substep>
        </substeps>
      </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>
          <p>For example, to mount the <filepath>source</filepath> subfolder of your home directory and bind it to the
              <filepath>/src</filepath> volume in the container:</p>
          <codeblock><cmdname>docker</cmdname> run -it \
  -v /Users/<varname>username</varname>/source:/src docker.pkg.github.com/dita-ot/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 <filepath>input.ditamap</filepath> file in your
              <filepath>source</filepath> folder as input, generates HTML5 output in <filepath>source/out</filepath> and
            displays build progress messages with verbose logging.</p>
          <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><cmdname>docker</cmdname> run -it \
  -v /c/Users/<varname>username</varname>/source:/src docker.pkg.github.com/dita-ot/dita-ot/dita-ot:<keyword keyref="maintenance-version"/> \
  -i /src/input.ditamap -o /src/out -f html5 -v</codeblock>
        </stepxmp>
      </step>
    </steps>
    <example>
      <title>Installing plug-ins in your own image</title>
      <p>To install custom plug-ins or make other changes based on the DITA-OT parent image, create your own
          <filepath>Dockerfile</filepath> and specify the official DITA-OT image as the basis for your image in the
          <filepath>FROM</filepath> directive.</p>
      <p>Each subsequent declaration in the Dockerfile modifies this parent image.</p>
      <p>For example:</p>
      <codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace">FROM docker.pkg.github.com/dita-ot/dita-ot/dita-ot:3.3.4

RUN dita --install https://example.com/plugin.zip
RUN dita --install from-plugin-registry</codeblock>
    </example>
  </taskbody>
</task><commit_msg>Add info on the ENTRYPOINT instruction<commit_after><?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="projects-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 log in to the GitHub Package 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>
          <li>To retrieve docker images from the GitHub Package Registry, you will also need a GitHub account.</li>
        </ul></p>
    </prereq>
    <steps>
      <step>
        <cmd>Install Docker for your operating system.</cmd>
        <choices>
          <choice>
            <xref href="https://docs.docker.com/docker-for-windows/install/" scope="external" format="html">Install
              Docker Desktop on Windows</xref>
          </choice>
          <choice>
            <xref href="https://docs.docker.com/docker-for-mac/install" scope="external" format="html">Install Docker
              Desktop on Mac</xref>
          </choice>
          <choice>On macOS, you can also install Docker Desktop via
            <xref keyref="homebrew"/>:
            <codeblock>$ <cmdname>brew cask install docker</cmdname>
<systemoutput>Downloading…</systemoutput></codeblock>
          </choice>
          <choice>On Linux, install Docker Community Edition (CE) via your operating system’s package manager, for
            example: <codeblock>$ <cmdname>sudo</cmdname> apt-get install docker-ce</codeblock></choice>
        </choices>
      </step>
      <step>
        <cmd>Log in to the GitHub Package Registry.</cmd>
        <substeps>
          <substep>
            <cmd>In your
              <xref href="https://github.com/settings/tokens" format="html" scope="external">GitHub profile
                settings</xref>, create a new personal access token with the <codeph>read:packages</codeph> scope.</cmd>
            <info>For more information, see
              <xref href="https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line"
                scope="external" format="html">Creating a personal access token for the command line</xref>.</info>
          </substep>
          <substep>
            <cmd>On the command line, run the <cmdname>docker</cmdname> command to log in with your GitHub
              credentials.</cmd>
            <stepxmp>
              <codeblock><cmdname>docker</cmdname> login docker.pkg.github.com -u <varname>USERNAME</varname> -p <varname>PASSWORD/TOKEN</varname></codeblock>
            </stepxmp>
            <info>For more information, see
              <xref
                href="https://help.github.com/en/articles/configuring-docker-for-use-with-github-package-registry#authenticating-to-github-package-registry"
                scope="external" format="html">Authenticating to GitHub Package Registry</xref>.</info>
          </substep>
        </substeps>
      </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>
          <p>For example, to mount the <filepath>source</filepath> subfolder of your home directory and bind it to the
              <filepath>/src</filepath> volume in the container:</p>
          <codeblock><cmdname>docker</cmdname> run -it \
  -v /Users/<varname>username</varname>/source:/src docker.pkg.github.com/dita-ot/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 <filepath>input.ditamap</filepath> file in your
              <filepath>source</filepath> folder as input, generates HTML5 output in <filepath>source/out</filepath> and
            displays build progress messages with verbose logging.</p>
          <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><cmdname>docker</cmdname> run -it \
  -v /c/Users/<varname>username</varname>/source:/src docker.pkg.github.com/dita-ot/dita-ot/dita-ot:<keyword keyref="maintenance-version"/> \
  -i /src/input.ditamap -o /src/out -f html5 -v</codeblock>
        </stepxmp>
        <info>
          <note>The DITA-OT container image uses the <codeph>ENTRYPOINT</codeph> instruction to run the
              <cmdname>dita</cmdname> command from the <filepath>/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>
    <example>
      <title>Installing plug-ins in your own image</title>
      <p>To install custom plug-ins or make other changes based on the DITA-OT parent image, create your own
          <filepath>Dockerfile</filepath> and specify the official DITA-OT image as the basis for your image in the
          <filepath>FROM</filepath> directive.</p>
      <p>Each subsequent declaration in the Dockerfile modifies this parent image.</p>
      <p>For example:</p>
      <codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace">FROM docker.pkg.github.com/dita-ot/dita-ot/dita-ot:3.3.4

RUN dita --install https://example.com/plugin.zip
RUN dita --install from-plugin-registry</codeblock>
    </example>
  </taskbody>
</task>
{'fraction_non_alphanumeric': 0.11240094536354789, 'fraction_numerical': 0.0015292645627693591, 'mean_word_length': 2.7751246392023092, 'pattern_counts': {'":': 0, '<': 381, '<?xml version=': 2, '>': 381, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '949103', 'n_tokens_mistral': 4130, 'n_tokens_neox': 3967, 'n_words': 1291}