A reproducible research environment with Sumatra and Docker

Docker is a promising candidate for a computational research environment that allows for easy replication of computations and results. Sumatra is an automated laboratory notebook for computational research projects. Do Sumatra and Docker work well together?

Yes! Here's some details that might help you get started using Docker and Sumatra in combination:

A docker image for Sumatra

I've created a basic docker image with Sumatra 0.7.0 and git bindings and uploaded it to the Docker Hub. The image felix11h/smt_docker is built from the following Dockerfile:

FROM ubuntu:14.04

RUN apt-get -y update
RUN apt-get install -y python python-dev python-pip

RUN apt-get install -y git
RUN pip install sumatra
RUN pip install gitpython



If you have Docker correctly installed, you can

docker run -it -p 8000:8000 felix11h/smt_docker /bin/bash

This command, after not finding the image felix11h/smt_docker locally, pulls the docker image created from the code above from the Docker Hub and runs it with the following parameters:

  • -i (--interactive) Keeps STDIN open even if not attached.
  • -t (--tty) Allocates a pseudo-TTY. Used here to run a throwaway interactive shell.
  • -p 8000:8000 (--publish) Publishes the container's port 8000 to the host. ip:hostPort:containerPort and hostPort:containerPort are the two formats I used so far.
  • /bin/bash Opens a Bash shell.

Sumatra within the container

From within the container, let's test if Sumatra works as expected:

mkdir smt_test
cd smt_test
git init
smt init Test_Project
smtweb --allips

Here, the flag --allips to smtweb is critical. It hosts the Sumatra web interface at (as opposed to, which is exactly the address the docker container assumes when trying to publish the content the host. (I was about to add this option to Sumatra myself, but found it was alrealdy there!)

With this you should be able to


from the Docker host (that is outside the container!). Or, of course, simply navigate to in your browser.

Mounting a data volume

If you want to save the results of computations that you're running within a container, mounting a data volume of your docker host to the container is likely the easiest solution. To do this, you have add yet another argument to the docker run command

docker run -v /path/to/host_dir:/path/to/container_dir ...

You might, for example, want to host the working directory to /home/wdir:

docker run -v $(pwd):/home/wdir ...

When dealing with data volumes, it's worth to think about permissions. I'm still experimenting with this, but a helpful command argument I found is

docker run --user="$(id -u):$(id -g)" ...

which, as I understand it, passes the current user.

Permanently host the web interface with screen

When running computational experiments within a Docker container, it would be great to be able to host the web interface and run simulations at the same time. An easy solution for this is to use screen. Install it in the container via

apt-get update
apt-get install screen

Then you can call screen, run smtweb --allips and detach the screen by pressing CTRL+a d. This allows you to keep the webinterface hosted while you're running simulations. To get back the original screen, use screen -r.

The neuroenv image (see below) has screen included.

Reproducible computational neuroscience simulations

At neuralensemlbe, Andrew Davison has provided a docker image cotaining NEST 2.6, NEURON 7.3, Brian 1.4 and PyNN 0.8.0rc1. The docker image I'm using in my current research project builds upon this neuralensemble/simulation image and additionally provides:

  1. Sumatra
  2. screen
  3. a mostly complete TeX Live installation

LaTeX was added for text rendering in Matplotlib. You can find this image under felix11h/neuroenv_smt_ltx on the Docker Hub.

Here's the shell script I have in my working directory to run the image conveniently:

sudo docker run -it -p --user="$(id -u):$(id -g)" -v $(pwd):/lab felix11h/neuroenv_smt_ltx /bin/bash

Let me know about your experience with Sumatra and Docker!