github The source code for this add-on is open source. You can use this project as a template for your own add-ons
Fork us on github!

Documentation can be redundant, time-consuming and let’s be honest, boring. As with most boring tasks, whenever possible, we like to automate. This is especially true when documenting things that change frequently. Thanks to our new add-on, we now enable you to automate documentation of infrastructure based on Docker Compose. Ardoq on-premise Docker stack

Our On-Premise installation uses Docker Compose (read more about our experience with Docker here and here). This is a great way to orchestrate your containers and is also a great basis for automatically generating documentation. So, we created an add-on that allows you to import your Docker Compose file into Ardoq. Now you can lean back, and watch your Docker stack being automatically documented and visualized.

The import shows all containers with volumes-from, links, the images that are used, and also the base images you use (as you see in the legend to the right).
Screen Shot 2015-12-29 at 22.20.04

Using the Docker Hub API, we also fetch the parent hierarchy of the images in the Docker Compose file and match that with the image hashes corresponding to all the tags in your repositories. All we need is a list of the repositories you use, and we can automatically discover the tags you depend on.

Below is the whole stack shown:

Automate it!

Keeping all the details up to date in your documentation is tedious and error prone. Connect your CI-system to the Docker Compose add-on, and you will never have outdated documentation again!

Automation is simply done with an HTTP POST to our Docker Addon Service. Here is an example using curl:

The Docker Compose file is in the POST body, and the parameters are as follows:

  • token: Ardoq API access token (personal)
  • org: Your organization account name in Ardoq
  • wsname: Name of the workspace to store the import
  • repos: Comma separated list of extra repositories to include in Docker parent image hierarchy search.
  • account: Optional Docker HUB account name.
  • password: Optional Docker Hub password.

If you’re concerned about security using your docker hub credentials, you can also run the add-on locally using Docker.

Extend it!

Do you have something more you would like to include in the import? The Docker Compose Add-on is open source, and 500 lines of fairly straight forward Clojure code.

What we discovered using the add on.

Discovery 1: Docker tags are moving targets

The most interesting thing we discovered using this illustration is the one thing that is missing!

We base all our custom images on Alpine Linux, but one of the images that is supposed to inherit from Alpine isn’t connected to the base image. This turns out to be because it has been a while since it was created, and uses a different version of alpine:3.2. Docker tags are not static, and can be updated even though the tag can look like a static version. The updated version can contain important security fixes, so it’s a good practise to update regularly.

Discovery 2: failure to standardize base images

We are supposed to use the same Java base image for all our Java applications. Writing this blog post, we discovered that this is not the case – our API uses a different version. This is easy to find out if you’re looking for it, but with the visualization it stares at you.

Shout out

If you have done anything cool, or just need help to get started, let us know! We love to hear real world usage scenarios, and are happy to help you out if you’re stuck.

Want to visualize your own Docker stack in Ardoq? Sign up or request a live demo from one of our team members!

Try it for yourself

Start a free 30-day trial of Ardoq