See also

Blogg update

Blogg on docker

Switching this Blogg from markdown to restructuredText is not as easy as it should be. I have to convert all the source files into a new format.

However, this does not address one of the problem I had with the initial (Octopress based) setup: running it on different hosts has an impact on how the site is rendered. Previously the issue was with several versions of Ruby Gems and Jekyll. This is based on multiple machines running on different release versions of the operating system.

With Sphinx, the problem basically stays unchanged: The versions of Sphinx differ (of course) between the distributions and releases. Quite a lot actually. That much, that I cannot render the site on the oldest machine I have.

I was thinking about centralising at least the rendering of the site and keeping the contribution of the source files decentralized. So far I did not do this step. Partly due to laziness, partly because I did not want to install the number of gems required on my server and possibly mess up something else.

With Sphinx it would not be based on Ruby gems, but the problem is the same: Different packages result in different versions of Sphinx which may or may not have support for the used features.

Before I go full in and render on the web server - though that feels like not a good idea - I have now chosen to move the Blogg rendering into a Docker container. I know that I can run Docker on all of my workstations. So putting the logic for rendering into a container, should keep the rendering based on the source code stable for the coming months, if not years.

The basic setup divided in modules looks now like this:

             ----------    -------------    ----------
local        | Source | -> | Rendering | -> | Upload |
             |        |    |   Docker  |    |        |
             ----------    -------------    ----------
remote                                     | Web host |




RST files for Sphinx, containing this Blogg. They are identical on all machines and versionized.


Previously Jekyll, now a moveable Docker image. The Jekyll installation could differ based on the release version. So could the Sphinx version. So could the Sphinx version. While the docker version can vary as well, the image doing the rendering is identical.


SSH based (rsync) upload. This module is so small and so stable, there is no win in keeping it in sync on all machines.

Web host

The web server serving this site.

The key is now, that by putting the rendering into a Docker container, I can move this container between hosts and guarantee the same result.

The source and the rendering are now both identical on all hosts, while it was only the source before.


While am I filling up the Blogg with more and more content from the previous years, I started measuring the rendering time, Once with Sphinx, once with Sphinx in Docker.

Local Sphinx

$ rm -r build/html/; time rake generate
sphinx-build-3 -b html -d build/doctrees   source build/html
Running Sphinx v1.4.8
making output directory...
Build finished. The HTML pages are in build/html.

real 0m2.955s
user 0m2.818s
sys  0m0.125s

Docker Sphinx

$ rm -r build/html/; time rake gd
rm: cannot remove 'build/html/': No such file or directory
sphinx-build-3 -b html -d build/doctrees   source build/html
Running Sphinx v1.5.2
making output directory...
Build finished. The HTML pages are in build/html.

## Site built with docker and image 'dbv/blogg'.

## Container removed.

real 0m7.118s
user 0m0.184s
sys  0m0.055s
  • As you can see from the output log, the version running in the Docker container is v1.5.2, while the local version is v1.4.8. For the rendering is does not make any difference, but this already illustrates the general problem.

  • Running the rendering locally takes 2.9 seconds. The Docker rendering takes two and three times as long (7.1 seconds). This is still in the range of an acceptable time frame.


With roughly 450MB the container is quite big compared to what should be possible. I tried to squash the image, but that only gave me 50MB extra. Optimizing the dockerfile is also as it’s limit.

I am open for suggestions.