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.s

Support has been added for packrat, which is a package dependency manager.

Pre-built docker images are published to DockerHub, and are based off the heroku/heroku:16 docker image to ensure compatibility for existing R applications which run on the heroku-16 stack.

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 will probably use the default setup, so it won't be necessary to have docker installed.

Usage

New R Applications

Run heroku create --stack=container from your R application source's root directory to create a container based application on Heroku.

Shiny Applications

These steps are for Shiny applications.

In your R application source's root directory:

• Create a Dockerfile file and insert the following content.

  FROM virtualstaticvoid/heroku-docker-r:shiny
  ENV PORT=8080
  CMD "/usr/bin/R --no-save -f /app/run.R"
  

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

  build:
    docker:
      web: Dockerfile

• Optionally, if you need to install additional R packages, you can use packrat to manage them.

  This is the recommended way to manage your R packages. Please see the packrat documentation for details.

• Commit the changes, using git as per usual.

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

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

  git push heroku <branch>

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 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:
      service: Dockerfile

• Optionally, if you need to install additional R packages, you can use packrat to manage them.

  This is the recommended way to manage your R packages. Please see the packrat documentation for details.

• Commit the changes, using git as per usual.

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

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

  git push heroku <branch>

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. It also provides greater control over the runtime directory layout and execution environment.

TO BE COMPLETED

Multi-Language Applications

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

This is out of the scope for this document, since there are too many permutations possible, however some examples are provided to help you get the idea.

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. 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 virtualstaticvoid/heroku-docker-r-examples repository.

Versions

The following table lists the docker image tags for each Heroku stack and R version combination:

Heroku Stack	R Version	Build Tag	Shiny Tag
heroku-16	3.4.4	virtualstaticvoid/heroku-docker-r:3.4.4-build	virtualstaticvoid/heroku-docker-r:3.4.4-shiny
heroku-18	3.5.2	virtualstaticvoid/heroku-docker-r:3.5.2-build	virtualstaticvoid/heroku-docker-r:3.5.2-shiny
heroku-18	3.5.2	virtualstaticvoid/heroku-docker-r:build	virtualstaticvoid/heroku-docker-r:shiny

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
• Packrat - Illustrates using packrat
• Python - Shows interoperability between Python and R
• Java - Shows interoperability between Java and R
• Ruby - Shows interoperability between Ruby and R

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.