What is Binder

Binder turns GitHub repositories into interactive environments using Jupyter

Example: https://github.com/Normaliz/NormalizJupyter

General workflow

  • Create a Docker image containing the software you want to use, which needs to have some requirements (later)

  • Give the image a unique tag and upload it to DockerHub

  • Create a GitHub repository containing your Jupyter notebooks and a small Dockerfile pointing to the main image

How to prepare images for Binder

First, install your software, for example python

FROM ubuntu:bionic
RUN apt-get update && apt-get install -y python

Now prepare the image for use with Binder!

Requirements for Binder images

The image must contain the Jupyter notebook, which can be installed via

RUN apt-get install -y python-pip
RUN pip install notebook
If you want to have JupyterLab available, install it via

RUN pip install jupyterlab_launcher jupyterlab traitlets ipython
RUN jupyter serverextension enable --py jupyterlab --user

Requirements for Binder image

The user which is used to start the image must have UID 1000. This can be achieved using the following snippet:


RUN adduser --disabled-password --gecos "Default user" \
            --uid ${NB_UID} ${NB_USER}
It is not necessary to use variables, but they will reappear later.

Build and upload the image

Build the image and upload it to DockerHub

$ docker build --tag="sebasguts/mybinderbase:20180604" .
$ docker push sebasguts/mybinderbase:20180604
You can use any tag except latest.

The good news

For GAP notebooks, you can also use the gapsystem/gap-docker-master repository now!

How to create shareable repositories

Using the base image you can share notebooks via GitHub. To do so, create a git repo with your notebooks in it and add a Dockerfile like this one:

FROM sebasguts/mybinderbase:20180604
USER root
RUN chown -R ${NB_UID} ${HOME}
Afterwards, upload it to GitHub and run it with Binder!

Further notes

  • To execute JupyterLab instead of notebook, type "lab" in the notebook filename field
  • If you change your baseimage, you need to give it a new tag, as Binder will not rebuild the image otherwise

The MyBinder badge

To include the "Run on MyBinder" badge add the following code to the repositories README

Binder Badge