D4ST System Overview

System Overview

A DITA for Small Teams system consists of four main components:
  1. A versioned source repository for managing the document source files (XML and non-XML media). Typical choices include git, Subversion, and Mercurial.
  2. A continuous integration server for automating production of output from the document source. Typical choices include Jenkins, Hudson, Bamboo, and GitLab.
  3. A link management server that maintains and provides access to the link nature of the DITA content. At the moment the D4ST Link Management application is the only open-source instance available. Link management is one of the key distinguishing features of most DITA-aware component content management systems (CCMS).
  4. An authoring tool by which authors can create and modify DITA source documents. There are many choices here, including oXygenXML, XMetal, FrameMaker, and a growing set of Web-based editors including FontoXML and XEditor.

In addition, if localization is a requirement, a D4ST system can also include a translation management system like XTM or Fluenta.

The D4ST container set provides the first three of the above components:
  • A container running a GitLab server provides both a central git repository server and a continuous integration server. GitLab was chosen in part because it provides both the versioning repository and the CI server.

    The git repository uses git hooks to communicate to the Link Management application whenever things are committed to the repository. Thus the git server must be able to connected over HTTP to the Link Management server. Having all the components within the same Docker environment makes this easy.

  • A container running the D4ST Link Manager, which uses the BaseX XQuery database. The Link Manager provides a Web application for authors to see and explore the link nature of their content and a REST API other applications, such as editors and production tools, can use to access the link details of the content.
  • A container for the DITA Open Toolkit. The Open Toolkit is managed in its own container to make it easier to change or update as needed. The OT container can also be used by itself as a convenient way to provision and manage Open Toolkit instances for whatever reason.

These containers are collected together using the Docker Compose facility, which manages starting and connecting a set of containers intended to work as a unit.

Of these containers, only the GitLab container requires a persistent data store because it is managing the document source. The other containers either have no need for persistent store or, in the case of the Link Management application, are essentially a read-only copy of the master git repository.

Thus the main configuration detail when running the container collection is connecting the GitLab container to the host machine's local file system. However, even this is optional if you use another git repository to maintain a copy of the container-managed git repo, for example, a private GitHub or Bitbucket repository. You also have the option of manually copying the files from the GitLab container to a local file system as a backup. Note that file systems within containers will be maintained as long as the container is not removed from the host machine.

Users interact with the D4ST containers as follows:
  • Authors create local git clones from the GitLab git server of the git repositories they contribute to. This is normal git interaction and is no different from using a git service like GitHub or Bitbucket. Authors simply need to know how to connect to the D4ST GitLab server, just as they would any other shared git server.
  • Authors work locally, create branches, etc., pushing their updates to the GitLab repository as appropriate. Whenever they push the git hooks on the GitLab server will update the Link Managed database in the Link Management container to reflect the changes. Authors can also configure their local git repository to contribute to the Link Management database or they can run a local Link Manager container on their own machine if they want to (or you can provision per-user Link Manager containers on a shared server, whatever makes sense).
  • Users use the GitLab CI server to produce outputs, either at user request or based on git commit events that you've configured with the GitLab CI server.