Publish and maintain markdown written documentations with daux.io, Docker and GitHub

Posted on September 04, 2016

As many of us will agree: Markdown is a great way to simply write documentations easy and quickly. daux.io is a documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you to create great looking documentation in a developer friendly way.

Daux.io is easy to install and easy to use. Nevertheless I was thinking about a solution how I can split up the documentation's source files from presenting the documentation with Daux.io. I came up with a simple approach where Daux.io is running in a Docker container and the documentation sources are hosted on GitHub. The container exposes an additional URL for GitHub WebHooks to trigger an update process of the documentation on git-push events.

Solution Overview

The docker image including a running Daux.io installation and the WebHook is available on DockerHub:

docker pull cokeschlumpf/daux.io:0.2.0

The sources are also published on GitHub.

Following I'll explain step by step how to setup the environment for this documentation solution on IBM Bluemix.

Step 1: Clone the Docker image and publish to your private Bluemix registry

First, clone the image from DockerHub:

docker pull cokeschlumpf/daux.io:0.2.0

To make the image available on your organizations Bluemix instance, tag the image with your organizations credentials:

docker tag cokeschlumpf/daux.io:0.2.0 registry.ng.bluemix.net/<your_namespace>/daux.io

Afterwards push the image to your Bluemix private repository:

docker push registry.ng.bluemix.net/<your_namespace>/daux.io

For further information see IBM Container Docs.

Step 2: Create & run container on Bluemix

Start the container on Bluemix as single container or container group. Optionally you can bind a Bluemix or custom URL to your container. For further details see IBM Container Docs.

Step 3: Create a repository with a WebHook for your documentation

Simply create a repository on GitHub including your documentation or fork my sample repository cokeschlumpf/daux.io-sample-docs.

Finally you'll need to create a WebHook in your repository which calls your container's update endpoint on every push:

http://<CONTAINER_IP>/update-webhook.php

GitHub Web Hook configuration

The first time update-webhook.php is called by GitHub it's initialized for the GitHub repository, only this repository can now effectively call the endpoint. When it's called, the repository's master branch is pulled from GitHub and the documentation will be updated in the container.

Michael Wellner

by Michael Wellner

Merzig, Saarland

www.michaelwellner.de