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`.
This approach uses the public binder cloud and requires no installation
Add the following components to your repository:
- A
Dockerfile
- Optionally, a badge to the
README.md
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.
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.
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.
✨ 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).
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.
- 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