What this package does
holepunch will read the contents of your R project on GitHub, create a DESCRIPTION file with all dependencies, write a Dockerfile, add a badge to your README, and build a Docker image. Once these 4 steps are complete, any reader can click the badge and within minutes, be dropped into a free, live, RStudio server. Here they can run your scripts and notebooks and see how everything works.
Motivation
Binder is an open source project that can take any most GitHub repos of notebooks (R or Jupyter) and turn them into a free, live instance that not only has all dependencies ready to go but also provides Jupyter or Rstudio server to run the code on. The instances are small and should not be used to demonstrate resource intensive computation. However they are ideal for reproducing papers/figures/examples and make a great addition to any public analysis project that is being hosted on GitHub.
Installation
remotes::install_github("karthik/holepunch")
# Please report any installation problems in the issuesSetting up your project as a compendium (recommended)
If you are unfamiliar with the idea of research compendia, I highly recommend reading this paper by Marwick et al:
Marwick B, Boettiger C, Mullen L. 2018. Packaging data analytical work reproducibly using R (and friends) PeerJ Preprints 6:e3192v2 https://doi.org/10.7287/peerj.preprints.3192v2
and also looking through my presentation at RStudio::conf 2019 where I talk about this in detail.
library(holepunch)
write_compendium_description(package = "Your compendium name",
description = "Your compendium description")
# to write a description, with dependencies. Be sure to fill in placeholder text
write_dockerfile(maintainer = "your_name")
# To write a Dockerfile. It will automatically pick the date of the last
# modified file, match it to that version of R and add it here. You can
# override this by passing r_date to some arbitrary date
# (but one for which a R version exists).
generate_badge() # This generates a badge for your readme.
# ----------------------------------------------
# At this time 🙌 push the code to GitHub 🙌
# ----------------------------------------------
# And click on the badge or use the function below to get the build
# ready ahead of time.
build_binder()
# 🤞🚀Alternate setup method
If for some reason you really don’t want to set up your project as a compendium, then set it up by creating runtime.txt and install.R. This build will take a very long time.
# Note that this particular approach will be super slow.
# And take just as long everytime you edit your code
library(holepunch)
write_install() # Writes install.R with all your dependencies
write_runtime() # Writes the date your code was last modified. Can be overridden.
generate_badge() # Generates a badge you can add to your README. Clicking badge will launch the Binder.
# ----------------------------------------------
# At this time 🙌 push the code to GitHub 🙌
# ----------------------------------------------
# Then click the badge on your README or run
build_binder() # to kick off the build process
# 🤞🚀Testing this package
An easy way to test this package without writing any code is to visit the binder-test repo and follow the instructions.
Roadmap
The ETA for the first release of this package is fall 2019 (after renv goes to CRAN). Comments, suggestions for improving the workflow or any other comments welcome in the issues. Other planned features include:
- Full support for GitHub packages
- Support for Bioconductor packages
- Reference Binders to separate environment from code (still in early planning)
Code of conduct
Please note that the ‘holepunch’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
