Make your examples live with binder

Loïc Estève

Inria

Main use case

  • Let anyone play with your software
  • in their browser without having to install anything

Useful for:

  • online tutorials/books as Jupyter notebooks
  • code for article with a demo of the algorithm on a simple dataset

Demo

Python (scikit-learn): repo, binder

C++: repo, binder

Rust: repo binder

What you need

  • a git repo URL (e.g. on github)
  • Jupyter notebooks inside the repo

A way to specify the environment for your notebook:

  • Python: that would be things like setup.py, requirements.txt (pip), environment.yml (conda)
  • generic: apt.txt for apt-get packages + postBuild for arbitrary shell commands
  • at last resort: you can use a Dockerfile, see this for more details.

Languages supported?

First citizens:

  • Python
  • R (RStudio is possible, rather than Jupyter notebook)
  • Julia

Any other language as long as:

  • you can install your language + environment through apt.txt + postBuild files
  • there is a Jupyter kernel for your language (see this for available languages)

Behind the scenes

  • repo2docker : create a Dockerfile from a github repo
  • JupyterHub (manages Jupyter notebook servers for multiple users)
  • deployed on a Kubernetes cluster in the cloud

Caveats

Mostly for simple demos:

  • 2 GB maximum memory usage
  • session restarted after 10 minutes of inactivity
  • 12 hours

Neighbor technologies

  • juniper: executable code embedded in the documentation. See SpaCy doc for more details.
  • Google colab: alternative, interesting especially if you need a GPU. A bit more hacky (installation instructions are part of the notebook)
  • sphinx-gallery: include Python examples inside the documentation + generate Jupyter notebooks (matplotlib gallery or scikit-learn gallery)

Summary

  • Not too much work to add to your repo
  • quite useful to let people get a quick feeling of your software without having to install it
  • mostly for demonstration

https://mybinder.readthedocs.io/en/latest/