How to document a docker image

Question

I have a docker image that receives a set of environment variables to customize its execution.

A simple example would be a web-server, that has stuff like client secret for OAuth2, a secret to sign cookies, etc.

The whole app is containerized on a docker image, that receives (runtime) environment variables.

I distribute that docker image on a private registry, and I would like to document that image, so that users can understand how they can customize the image.

Is it possible to ship, as part of the docker image, annotations that e.g. using docker describe my_image output markdown to the stdout?

I could of course use a static page on the web for documentation, but the user would still need to know where that documentation could be found, and the whole distribution would be more complext this way (e.g. documentation changes with image tag).

Any ideas?

Answer 1

There is no silver bullet here as far as I know, All solutions below work, but require the user to be informed of how to retrieve the documentation. There is no standard way of doing it.

The open container initiative have created an image spec annotation suggesting that

• A link to more information about the image should be provided in a label called org.opencontainers.image.documentation.
• A description of the software packaged inside the container should be provided in a label called org.opencontainers.image.description

According to OCI, one of the variations of option 1 below is correct.

Option 1: Providing a link in a label (Prefered by OCI)

Assuming the Dockerfile and related assets are version controlled in a git repository that is publicly accessible (for example on github), that git repository could also contain a README.md file. If you have a pipeline hooked up to the repo that builds and publishes the Docker image to a registry automatically, you could setup the docker build command to add a label with a link to the documentation as follows

# Get the current commit id
commit=$(git rev-parse HEAD)

# Build docker image and attach a link to the Readme as a label
docker build -t myimagename:myversion \
--label "org.opencontainers.image.documentation=https://github.com/<user>/<repo>/blob/$commit/README.md"

This solution links to specific commit documentation for that particular commit versioned alongside your Dockerfile. It does however require the user to have access to internet to be able to read the documentation

Option 1b: Providing full documentation in a label (Prefered by OCI)

A variation of option 1 where the full documentation is serialized and put into the label (there is no length restrictions on labels). This way the documentation is bundled with the image itself

As Jorge Leitao pointed out in the comments, the image annotaion spec from OCI specifies the name of such a label as org.opencontainers.image.description

Option 2: Bundling documentation inside image

If you prefer to actually bundle the Readme.md file inside the image to make it independent on any external web page consider the following

Upon build, make sure to copy the Readme.md file to the docker image Also create a simple shell script describe that cats the Readme.md

describe

#!/usr/bin/env sh
cat /docs/Readme.md

Dockerfile additions

...
COPY Readme.md /docs/Readme.md
COPY describe /opt/bin/describe
RUN chmod +x /opt/bin/describe
ENV PATH="/opt/bin:${PATH}"
...

A user that have your Docker image an now run the following command to have the markdown sent to stdout

docker run myimage:version describe

This solution bundles the documentation for this particular version of the image inside the image and it can be retrieved without any external dependencies