Running the dita command from a Docker image
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.
About application containers
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.
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.
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.
Before you begin
- To download Docker Desktop, you may be prompted to sign in with your Docker ID (or sign up to create one).
- To retrieve docker images from the GitHub Package Registry, you will also need a GitHub account.
Install Docker for your operating system.
- Install Docker Desktop on Windows
- Install Docker Desktop on Mac
- On macOS, you can also install Docker Desktop via
$ brew cask install docker Downloading…
- On Linux, install Docker Community Edition (CE) via your operating system’s package manager, for
$ sudo apt-get install docker-ce
Log in to the GitHub Package Registry.
settings, create a new personal access token with the
reposcopes.For more information, see Creating a personal access token for the command line.
On the command line, run the docker command to log in with your GitHub
docker login docker.pkg.github.com -u USERNAME -p PASSWORD/TOKENFor more information, see Authenticating to GitHub Package Registry.
- In your GitHub profile settings, create a new personal access token with the
To build output, map a host directory to a container volume and specify options for the
$ docker run -it \ -v /Users/username/source:/src docker.pkg.github.com/dita-ot/dita-ot/dita-ot:3.6 \ -i /src/input.ditamap \ -o /src/out \ -f html5 -vThis command sequence specifies the following options:
- -v mounts the source subfolder of your home directory and binds it to the /src volume in the container
- -i specifies the input.ditamap file in your source folder as the input map file
- -o writes the output to source/out
- -f sets the output format to HTML5, and
- -v displays build progress messages with verbose logging
On Windows, if your Users directory is on the C:\ drive, use /c/Users/… to map the host directory:
> C:\Users\username> docker run -it ^ -v /c/Users/username/source:/src docker.pkg.github.com/dita-ot/dita-ot/dita-ot:3.6 ^ -i /src/input.ditamap ^ -o /src/out ^ -f html5 -vNote: The DITA-OT container image uses the
ENTRYPOINTinstruction to run the dita command from the /opt/app/bin/ directory of the container automatically, so you there’s no need to include the dita command itself, only the arguments and options you need to publish your content.