DOCKument is a tool that helps you auto-generate documentation for your Dockerfiles and Docker images the way you would an API.

Matthias Lübken gave an example on how to use “API” like labels to describe important information in the Dockerfile (e.g., resources used, exposed ports, dependencies, etc) here. This project makes use of similar label patterns to fetch important data in Dockerfiles / Docker images and create Dockumentation for it automagically. Furthermore, it improves on the work done by Matthias to expose various kinds of information that can be fetched from Docker images.

In this post we will go through the usecase, usage, pre-reqs, getting started, and a little teaser for the next post.

Usecases

Dockument on its own is just a tool that gives you the ability to fetch information out of Dockerfiles or built images. You can choose to create a Markdown output of your Dockerfile and Docker image or you can cherry pick on what to fetch from the image and visualize it’s content. Although this is not the main strength point of Dockument, it can come in handy when trying to share your Dockerfile on a public repo, it instantly allows the readers to understand the highlights of your Dockerfile / image (e.g., resources exposed, environment variables, dependencies, tests, and much more).

The use-case above reflects the usage of Dockument only as a tool. What we can also do with Dockument, which I personally consider to be the main strength point, is using it as a framework for fetching important information out Docker images. If used in this manner, other tools can use this information to provide useful utilities as will be described in my next post about Docktorino the contious testing tool for Docker images.

How to Use it

With DOCKument you have the option to fetch important information about your Dockerfile or Docker images direcly from the command line OR create a markdown document that you can add to your git REPO or share with other developers.

For example, if you type dockument deps -d "../examples/Dockerfile", you will get the following output which describes the dependencies of this container image:

### Dependency RABBIT ###
	Application: rabbit
	Image: "rabbit:latest"
	Description: "The rabbit"
	Ports: ["5271"]
	Required: "true"

### Dependency REDIS ###
	Application: redis
	Image: "redis:latest"
	Description: "For caching results from OWM API."
	Ports: ["6379"]
	Required: "true"

On the other hand, to create a markdown DOCKument, you can use dockument create --dockerfile "../examples/Dockerfile" -o "$HOME/dockumentation.md" or dockument create --image "repo/name:tag" -o "$HOME/dockumentation.md" . The output will be a file similar to the one here

Pre-reqs

There are two types of labels that Dockument supports, these are:

You can use Dockument to print or create a documentation of random metadata in your Dockerfile or Docker images, however, that is not very useful. To utilize the fully-fledged functionality of Dockument, define labels in your Docker images that follow the below pattern.

For Dependencies:

Will this containerized application have dependencies on other applications?

LABEL api.DEPENDENCY.redis=""\
      api.DEPENDENCY.redis.image="redis:latest"\
      api.DEPENDENCY.redis.port="6379"\
      api.DEPENDENCY.redis.about="For caching results from OWM API."\
      api.DEPENDENCY.redis.mandatory="true"

For Important ENVs:

What are the environment variables that this container image defines?

LABEL api.ENV.OPENWEATHERMAP_APIKEY="" \
      api.ENV.OPENWEATHERMAP_APIKEY.about="Access key for OpenWeatherMap. See http://openweathermap.org/appid for details." \
      api.ENV.OPENWEATHERMAP_APIKEY.mandatory="true"

For Exposed Ports:

Do we expose any ports?

LABEL api.EXPOSE.1337="" \
      api.EXPOSE.1337.scheme="tcp" \
	api.EXPOSE.1337.protocol="http"\
      api.EXPOSE.1337.about="The main endpoint of this service."

For resources used by the container image:

What resources are required by my application to run in a smooth and performant manner?

LABEL api.RESOURCES.Memory="3gb"\
      api.RESOURCES.CPU="2"

For Important Tags

What are some important tags that I want my Dockerfile to expose?

LABEL api.TAGS.go="1.9"

For Container Tests

Tests help you make sure that your container image conforms with what you actually wants it to do. To this end, we decided to support the container-structured-test style. There are four types that are supported by Dockument:

LABEL api.TEST.command=""\
      api.TEST.command.name="go version"\
      api.TEST.command.command="go"\
      api.TEST.command.args="version"\
      api.TEST.command.expectedOutput="go version"

LABEL api.TEST.fileExistence=""\
      api.TEST.fileExistence.name="Dockumentation Check"\
      api.TEST.fileExistence.path="/dockumentation.md"\
      api.TEST.fileExistence.shouldExist="true"\
      api.TEST.fileExistence.permissions=""

LABEL api.TEST.fileContent=""\
      api.TEST.fileContent.name="Debian Sources"\
      api.TEST.fileContent.path="/etc/apt/sources.list"\
      api.TEST.fileContent.expectedContents="['.*httpredir\\.debian\\.org.*']"\
      api.TEST.fileContent.excludedContents="['.*gce_debian_mirror.*']"

LABEL api.TEST.metadata=""\
      api.TEST.metadata.env="GOPATH:/go"\
      api.TEST.metadata.exposedPorts=""\
      api.TEST.metadata.volumes=""\
      api.TEST.metadata.cmd=""\
      api.TEST.metadata.workdir=""

By now, I am guessing you might have an idea of how labels are defined and what Dockument does, but you are missing a little demo to get the gist of it, so lets do just that.

For a complete example, please have a look at this Dockerfile or this Dockerfile by luebken

Getting Started

To get started, visit the github repo for DOCKument and download the corresponding binaries, or build it yourself :)

Next Post

As mentioned earlier in this post, Dockument can be either used as a tool or as a framework that other tools can capitalize on. In the next post, we will be taking about Docktorino, a real-time continious testing tool for your docker builds that will help you containerize with confidence!