Awesome

Heroku R Docker Image

This is the docker image for applications which use R for statistical computing and CRAN for R packages, running on Heroku.

This project is compatible with the heroku-buildpack-r so that it is possible to migrate your existing Heroku R applications and deploy them using the new Heroku container stack, however there are some caveats if multiple buildpacks were used together with heroku-buildpack-r.

The new stack alleviates many of the complexities and issues with the R buildpack.

Pre-built docker images are published on GitHub Container Registry, and are based off the official Ubuntu docker images. Previous versions were published to Docker Hub.

Support has been added for packrat and renv package managers.

NOTE: Docker is not required to be installed on your machine, unless you need to build and run the images locally. For the most common use cases, you can probably use the default configuration so it won't be necessary to have docker installed.

Usage

Shiny Applications

These steps are for Shiny applications.

In your Shiny application source's root directory:

• Create a Dockerfile file and insert the following content.

  FROM ghcr.io/virtualstaticvoid/heroku-docker-r:shiny
  ENV PORT=8080
  CMD ["/usr/bin/R", "--no-save", "--gui-none", "-f", "/app/run.R"]
  

• Create a heroku.yml file and insert the following content.

  build:
    docker:
      web: Dockerfile
  

• Commit the changes, using git as per usual.

  git add Dockerfile heroku.yml
  git commit -m "Using heroku-docker-r FTW"
  

• Create the Heroku application with the container stack

  heroku create --stack=container
  

  Or configure an existing application to use the container stack.

  heroku stack:set container
  

• Deploy your application to Heroku, replacing <branch> with your branch. E.g. master.

  git push heroku <branch>
  

• Scale the web dyno

  heroku scale web=1
  

See heroku-docker-r-shiny-app for an example application.

Plumber Applications

These steps are for Plumber applications.

In your Plumber application source's root directory:

• Create a Dockerfile file and insert the following content.

  FROM ghcr.io/virtualstaticvoid/heroku-docker-r:plumber
  ENV PORT=8080
  CMD ["/usr/bin/R", "--no-save", "--gui-none", "-f", "/app/app.R"]
  

• Create a heroku.yml file and insert the following content.

  build:
    docker:
      web: Dockerfile
  

• Commit the changes, using git as per usual.

  git add Dockerfile heroku.yml
  git commit -m "Using heroku-docker-r FTW"
  

• Create the Heroku application with the container stack

  heroku create --stack=container
  

  Or configure an existing application to use the container stack.

  heroku stack:set container
  

• Deploy your application to Heroku, replacing <branch> with your branch. E.g. master.

  git push heroku <branch>
  

• Scale the web dyno

  heroku scale web=1
  

See heroku-docker-r-plumber-app for an example application.

Other R Applications

These steps are for console and other types of R applications.

In your R application source's root directory:

• Create a Dockerfile file and insert the following content.

  FROM ghcr.io/virtualstaticvoid/heroku-docker-r:build
  CMD ["/usr/bin/R", "--no-save", "-f", "/app/<R-program>"]
  

  Change <R-program> to the main R program you want to have executed. E.g. app.R.

• Create a heroku.yml file and insert the following content.

  build:
    docker:
      app: Dockerfile
  

• Commit the changes, using git as per usual.

  git add Dockerfile heroku.yml
  git commit -m "Using heroku-docker-r FTW"
  

• Create the Heroku application with the container stack

  heroku create --stack=container
  

  Or configure an existing application to use the container stack.

  heroku stack:set container
  

• Deploy your application to Heroku, replacing <branch> with your branch. E.g. master.

  git push heroku <branch>
  

• Run the application

  heroku run app
  

Applications with Additional Dependencies

For R applications which have additional dependencies, the container stack gives you much more flexibility with the Dockerfile than was previously available in the R buildpack; such as for installing dependencies from other sources, from deb files or by compiling libraries from scratch, or using docker's multi-stage builds. It also provides greater control over the runtime directory layout and execution environment.

To make it easier for project authors to manage dependencies and provide backward compatibility with the heroku-buildpack-r without the need for Docker to be installed, the following functionality is provided:

In each of the following examples, Docker's ONBUILD method is used to execute the step when the respective file is detected.

• init.R

  Maintaining compatibility with the heroku-buildpack-r, the init.R file is still supported and is used to install any R packages or config R as necessary.

  In addition, an R helper function, called helper.installPackages is provided to simplify installing R packages. The function takes a list of R package names to install.

  During the deployment process, the existence of the ./init.R file will cause the script to be executed in R.

  E.g. This example installs the gmp R package.

  # install additional packages, using helper function
  helpers.installPackages("gmp")
  

• Aptfile

  Create a text file, called Aptfile in your project's root directory, which contains the Ubuntu package names to install.

  During the deployment process, the existence of the ./Aptfile file will cause the packages to be installed using apt-get install ....

  E.g. This example Aptfile installs the GNU Multiple Precision Arithmetic library and supporting libraries.

  libgmp10
  libgmp3-dev
  libmpfr4
  libmpfr-dev
  

  This is based on the same technique as used by the heroku-buildpack-apt buildpack.

• onbuild

  Create a Bash script file, called onbuild in your project's root directory, containing the commands you need to install any dependencies, language runtimes and perform configuration tasks as needed.

  During the deployment process, the existence of the ./onbuild file will cause it to be executed in Bash.

  E.g. This example onbuild file installs Ubuntu packages.

  #!/bin/bash
  set -e # fail fast
  
  # refresh package index
  apt-get update -q
  
  # install "packages"
  apt-get install -qy packages-names
  
  # reduce the image size by removing unnecessary Apt files
  apt-get autoclean
  

  NOTE: Change "packages-names" to the list of packages you wish to install.

  See Java, Python and Ruby for examples of using the onbuild Bash script.

• packrat

  If you want to install and manage R packages more reliably, you can use packrat to manage them. Please see the packrat documentation for further details.

  During the deployment process, the existence of the ./packrat/init.R file will cause Packrat to be bootstraped and the referenced packages installed.

  It is recommended to include a .dockerignore file in your project's root directory, in order to exclude unnecessary directories/files being included from the packrat subdirectory.

  E.g. Example .dockerignore

  packrat/lib*/
  

  NOTE: packrat has been soft-deprecated in favour of renv.

• renv

  If you want to install and manage R packages more reliably, you can use renv to manage them. This is the recommended way to manage your R packages. Please see the renv documentation for further details.

  During the deployment process, the existence of the ./renv/activate.R file will cause renv to be bootstraped and the referenced packages installed.

  It is recommended to include a .dockerignore file in your project's root directory, in order to exclude unnecessary directories/files being included from the renv subdirectory.

  E.g. Example .dockerignore

  renv/library/
  renv/python/
  renv/staging/
  

Multi-Language Applications

For applications which use another language, such as Java, Python or Ruby to interface with R, the container stack gives you much more flexibility and control over the environment, however the onus is on the developer to configure the language stack within the docker container instead of with mulitple buildpacks.

In each example, the language runtime can be installed via the use of an onbuild Bash script, which must be in the root of the project directory, and which is invoked during the deployment process.

This shell script can run installations such as using apt-get for example, or any other commands to setup language support and perform configuration as needed.

There are of course many permutations possible, so some examples are provided to help you get the idea:

• Java

  The Java example installs the OpenJDK, configures R accordingly and compiles the project's Java source files.

• Python

  In the Python example, the onbuild installs the Python runtime and installs the project dependenecies using pip.

• Ruby

  The Ruby example installs the runtime and then installs the project dependencies using bundler.

Existing R Applications

For R applications which use the heroku-buildpack-r, this project provides backward compatibility so that you can continue to enjoy the benefit of using Heroku to deploy and run your application, without much change.

The process continues to use your init.R file in order to install any packages your application requires. Furthermore, the Aptfile continues to be supported in order to install additional binary dependencies.

It is worth nothing that use of multiple buildpacks is not supported nor needed on the container stack, so you may have some rework to do if you made use of this feature.

Please see the MIGRATING guide for details on how to migrate your existing R application.

Speeding Up Deploys

Since the container stack makes use of docker together with a Dockerfile to define the image, it is possible to speed up deployments by pre-building them.

NOTE: This requires having docker installed and an account on Docker Hub or other Heroku accessible container registry.

An example of how this is done can be found in the "speedy" example application.

Versions

The following versions for ghcr.io/virtualstaticvoid/heroku-docker-r are available on GitHub Container Registry, including:

Previous versions for virtualstaticvoid/heroku-docker-r are available on Docker Hub, including:

Examples

The examples repository contains various R applications which can be used as templates.

They illustrate usage of the docker image and the configuration necessary to deploy to Heroku.

• Shiny - An example Shiny application
• Plumber - An example Plumber application
• Packrat - Illustrates using packrat
• Renv - Illustrates using renv
• Python - Shows interoperability between Python and R
• Java - Shows interoperability between Java and R
• Ruby - Shows interoperability between Ruby and R

Credits

• Original heroku-buildpack-r for "buildpack" API.
• Snippets from the rstudio/r-docker project.
• Snippets from the rstudio/r-builds project.

License

MIT License. Copyright (c) 2018 Chris Stefano. See MIT_LICENSE for details.

Additional Information

R is "GNU S", a freely available language and environment for statistical computing and graphics which provides a wide variety of statistical and graphical techniques: linear and nonlinear modelling, statistical tests, time series analysis, classification, clustering, etc. Please consult the R project homepage for further information.

CRAN is a network of FTP and Web Servers around the world that store identical, up-to-date, versions of code and documentation for R.