tomaugspurger / binder

Adds binder to tidyverse, providing JupyterHub

rocker/binder

Adds binder abilities on top of the rocker/geospatial images.

For documentation for R >= 4.0.0, for images r-ver, rstudio, tidyverse, verse, geospatial, shiny, and binder, please see the rocker-versioned2 repository`.

Deploy methods

Using mybinder.org services

This approach uses the public binder cloud and requires no installation

Add the following components to your repository:

1. A Dockerfile
2. Optionally, a badge to the README.md

Dockerfile

Add a file named Dockerfile with the following contents to the root of a GitHub repository:

## Use a tag instead of "latest" for reproducibility
FROM rocker/binder:latest

## Declares build arguments
ARG NB_USER
ARG NB_UID

## Copies your repo files into the Docker Container
USER root
COPY . ${HOME}
## Enable this to copy files from the binder subdirectory
## to the home, overriding any existing files.
## Useful to create a setup on binder that is different from a
## clone of your repository
## COPY binder ${HOME}
RUN chown -R ${NB_USER} ${HOME}

## Become normal user again
USER ${NB_USER}

## Run an install.R script, if it exists.
RUN if [ -f install.R ]; then R --quiet -f install.R; fi

If you add an install.R file to the root directory of your GitHub repo as well, any R commands in that file will automatically be run as well. This should make it easier for users to install additional R packages from CRAN, GitHub etc by just writing R code to do so.

Note You can extend this Dockerfile if necessary to include additional system dependencies; see Troubleshooting below.

Badge

To launch on https://mybinder.org, go to that address and enter the https address of your GitHub repository. You can also create a shiny badge for your README.md by adding the following markdown text:

[![Binder](http://mybinder.org/badge.svg)](http://beta.mybinder.org/v2/gh/<GITHUB_USER>/<REPO>/<BRANCH>?urlpath=rstudio)

filling in <GITHUB_USER>, <REPO> and <BRANCH> as appropriate. The usethis::use_binder_badge() function does this for you.

Here is an example badge to launch the binder-examples/dockerfile-rstudio repo.

See the binder/ subdirectory for a minimal example. Note: you can always put your Dockerfile in binder/Dockerfile if you don't want to put it in the root directory.

Running on your own machines, Using Docker

This approach works on any machine on which you have Docker installed.

The rocker/binder images can be run like any other docker image:

docker run -p 8888:8888 rocker/binder

Note that binder will run Juyter Notebook on port 8888 by default. The above command will print to the terminal (and the docker container log) the URL which includes a randomly generated token for secure login, so be sure to include that in the URL you paste into the browser.

Opening RStudio once Binder Launches

✨ NEW ✨: By including ?urlpath=rstudio on the binder urls in the examples above, Binder should automatically open in an RStudio instance, rather than a Jupyter notebook. Otherwise, see the documentation below for navigating to an RStudio instance from Jupyter:

Old method: Once inside Jupyter Notebook, RStudio Server should be an option under the menu "New":

That should start you into an RStudio session (with no further login required).

Troubleshooting

It didn't work! What do I do now?. If you are installing additional R packages, this will sometimes fail when a package requires an external library that is not found on the container. We're working on a more elegant solution for this case, but meanwhile, you'll need to modify the Dockerfile to install these libraries. For instance, the gsl R package page reads

SystemRequirements:	Gnu Scientific Library version >= 1.12

To solve this, you will need to add the following line to your Dockerfile, right after the line that says USER root:

RUN apt-get update && apt-get -y install libgsl-dev

Or, just get in touch by opening an issue. We'll try and resolve common cases so more things work out of the box.

Credits

• Ryan Lovett for writing the core part of this, nbrsessionproxy.
• Taylor Reiter for testing & shaping this.
• Yuvi Panda & Aaron Culich for bringing it together on Binder.
• Chris Holdgraf for this nice GIF
• Tim Head for this nice GIF