Outline

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: 

ENV NB_USER gap
ENV NB_UID 1000
ENV HOME /home/${NB_USER}

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
COPY . ${HOME}
USER root
RUN chown -R ${NB_UID} ${HOME}
USER ${NB_USER}
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](https://mybinder.org/badge.svg)]
(https://mybinder.org/v2/gh/github-username/repository-name/master)
Binder Badge