About Docker

The Docker system makes it easy to package and run software on any platform.

The Docker technology lets you package software components or files into modular containers that can be run on any platform. Each container is a Linux virtual machine. Docker is free open source. The main Docker Web site is https://docker.com.

Docker is fundamentally a Linux-based technology, so even if you are using Docker on Windows or OS X you will need to be familiar with a few basic Linux commands and be comfortable using a command-line shell. You can even use ready-made Docker containers that provide full graphical Unix environments like Ubuntu, accessible through VNC if you want.

The Docker platform manages getting, maintaining, and running Docker containers on a host machine. When the host machine is itself a Linux machine the Docker containers can be run directly by the host operating system. For Windows and OSX, if you use the Docker for Windows or Docker for Mac versions of Docker then the Docker containers appear to be running directly on the host operating system just like for Linux. If you are using the older Docker Machine version of Docker under Windows or OSX then things are slightly more complicated. These instructions assume you are using Docker for Windows or Docker for Mac or that you are using Linux.

The Docker platform includes a public container library, the Docker Hub, which any one can use to make their containers publicly available. When you attempt to run a container for the first time, Docker will automatically try to get it from the Docker Hub for you. This makes deploying and updating software about as easy as it can be.

Docker containers can be tagged, usually to reflect specific release versions. In the case of the DITA Open Toolkit containers, the tags are used to reflect the DITA Open Toolkit version used in the container. By default, Docker will look for a container with the tag "latest" but you can specify a tag when running or getting a container. For example, to use the 1.8.5 Open Toolkit you would specify the tag "1.8.5" as part of the docker run command:
$ docker run -it ditaot/dita-ot:1.8.5
root@39245ead9d45:~/DITA-OT#
The DITA Open Toolkit Docker image serves two main purposes:
  1. It provides a working Open Toolkit you can run against your DITA source just as you would any Open Toolkit
  2. It provides access to the Open Toolkit files to other containers, such as continuous integration (CI) servers like Jenkins and GitLab, that want to run the Open Toolkit, and XML processors that need the Open Toolkit-managed entity resolution catalogs (catalog-dita.xml in the Open Toolkit).

Docker containers are defined using configuration files named Dockerfile (by convention). A given Docker container is always based on another container, either one of the Docker-provided base containers, which provide the base operating system for the container, usually a minimal Linux environment, or a more specialized environment. For example, the DITA Open Toolkit base container is itself based on the "java:8" container, since the Open Toolkit is a Java-based application. By basing one container on another you can quickly build up systems of containers with different configurations with a minimum of duplication. Containers are stored as layered file systems and layers that are the same are shared across containers, making it efficient to have different containers that have only small differences from their base containers.

Docker containers can connect to the host operating system or Docker machine by defining volumes. Volumes are directories within the container that can be connected to host machine or Docker machine directories. Managing volumes and understanding how your local machine's directory structure relates to a given Docker container's volumes is probably the most complicated aspect of using Docker containers.

Docker containers are intended to be ephemeral, meaning that they can be created and destroyed, started and stopped quickly. As such they do not provide any built-in persistent storage. When a container stops or is removed any changes made within the container are lost. So it is important to understand how to capture anything you want to keep, such as the output of the DITA Open Toolkit. This document tries to describe the processes and practices for doing this on Windows and OS X.

To use Docker on Windows and OS X you must install Docker for Windows or Docker for Mac.

Docker for Windows and Docker for Mac provide tight integrations of the Docker environment with your machine, making it as easy as possible to use Docker containers. By default all the directories under /Users (Mac) or c:/Users (Windows) are available for read/write access from Docker containers. Containers that provide Web applications or are otherwise network addressable will be accessible at "localhost" or at your host's external IP address or network name (if it has one).