heroku-buildpack-r

by dpmccabe

GitHub Readme.md

Heroku buildpack: R

This is a Heroku buildpack for applications which use R for statistical computing and CRAN for R packages.

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.

It also includes support for the Shiny web application framework.

Usage

To use this version, the buildpack URL is http://github.com/virtualstaticvoid/heroku-buildpack-r.git#heroku-16.

The buildpack will detect your app makes use of R if it has an init.R or run.R file in the root directory.

If only a run.R file is found, then the buildpack will be configured as a Shiny application.

The R runtime is vendored into your slug, and the init.R program is executed in order to install any additional R packages.

Installing R Packages

The init.R file is executed during slug compilation, so it can be used to install R packages if required.

The following file can be used to install packages if they aren't already installed.

Add the package names you want to install to the my_packages list:

# init.R
#
# Example R code to install packages if not already installed
#

my_packages = c("package_name_1", "package_name_2", ...)

install_if_missing = function(p) {
  if (p %in% rownames(installed.packages()) == FALSE) {
    install.packages(p)
  }
}

invisible(sapply(my_packages, install_if_missing))

R packages can also be installed, by providing a tar.gz package archive file, if a specific version is required, or it is not a published package. See local-packages for an example.

# init.R
#
# Example R program to installed package from local path
#

install.packages("/app/PackageName-Version.tar.gz", repos=NULL, type="source")

NOTE: The path to the package archive needs to be an absolute path, based off the /app root path, which is the location of your applications files on Heroku.

Installing Binary Dependencies

If the R packages have binary dependencies, they can be specified by providing an Aptfile which contains the Ubuntu package names to install.

Examples include gmp, rgeos and topicmodels where Ubuntu packages are installed during slug compilation.

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

R Console

You can run the R console application as follows:

$ heroku run R ...

Type q() to exit the console when you are finished.

You can run the Rscript utility as follows:

$ heroku run Rscript ...

Note that the Heroku slug is read-only, so any changes you make during the session will be discarded.

Shiny Applications

Shiny applications must provide the run.R file, but can also include an init.R in order to install additional R packages. The Shiny package does not need to be installed, as it is included in the buildpack already.

The run.R file should contain at least the following code, in order to run the web application. The PORT environment variable, provided by Heroku, is used to configure Shiny accordingly, and the host should be 0.0.0.0.

library(shiny)

port <- Sys.getenv('PORT')

shiny::runApp(
  appDir = getwd(),
  host = '0.0.0.0',
  port = as.numeric(port)
)

Scheduling a Recurring Job

You can use the Heroku scheduler to schedule a recurring R process.

An example command for the scheduler, to run prog.r, would be R -f /app/prog.r --gui-none --no-save.

Technical Details

R Versions

The buildpack uses R 3.4.0 by default, however it is possible to use a different version if required. This is done by providing a .r-version file in the root directory, which contains the R version to use.

The following R versions are provided on the heroku-16 stack:

  • 3.3.3
  • 3.4.0
  • 3.4.1
  • 3.4.2
  • 3.4.3

Buildpack Versions

To reference a specific version of the buildpack, add the Git branch or tag name to the end of the build pack URL when creating or configuring your Heroku application.

E.g. Replace branch_or_tag_name with the desired branch or tag name:

$ heroku create --stack heroku-16 \
    --buildpack http://github.com/virtualstaticvoid/heroku-buildpack-r.git#branch_or_tag_name

NOTE: The .buildpack-version file is no longer supported and will be ignored.

Buildpack Binaries

The binaries used by the buildpack are hosted on AWS S3 at https://heroku-buildpack-r.s3.amazonaws.com.

See the heroku-buildpack-r-build repository for building the R binaries yourself.

Process Types

The buildpack includes the following default process types:

  • console: Executes bash in the chroot context, if needed for debugging.
  • web: Executes run.R to run Shiny in the chroot context

The R and Rscript executables are available like any other executable, via the heroku run command.

Fake Chroot

This version of the buildpack uses a fake chroot in order to properly support R on Heroku. This is because R presents some unique challenges when used on Heroku. Checkout the comments in bin/compile for more details.

The directory layout of the buildpack places the chroot in /app/.root and symlinks /app into /app/.root/app so that file paths are unaffected.

NB: If your application provides a Procfile to provide it's own process types, you may need to include the fakechroot fakeroot chroot command with the chroot path /app/.root, to execute your application correctly.

For example, this command runs bash within the chroot context:

fakechroot fakeroot chroot /app/.root /bin/bash

NOTE: During tests of the buildpack, the normalizePath R function failed for the symlinked /app path within the chroot context, so it is overridden in Rprofile.site file in order to work correctly, however YMMV if you use additional symlinks within /app of your application.

Multiple Buildpacks

This buildpack can be used in conjunction with other supported language stacks on Heroku by using multiple buildpacks. See Using Multiple Buildpacks for an App.

See the ruby application which shows how to use R together with a Ruby Sinatra web application and the rinruby gem.

CRAN Mirror Override

It is possible to override the default CRAN mirror used, by providing the URL via the CRAN_MIRROR environment variable.

E.g. Override the URL by setting the variable as follows. Note: There is no trailing "slash" in the URL.

heroku config:set CRAN_MIRROR=http://cloud.r-project.org

Check the CRAN mirror status page to ensure the mirror is available.

Caveats

Due to the size of the R runtime, the slug size on Heroku, without any additional packages or program code, is approximately 150Mb. If additional R packages are installed then the slug size will increase.

Credits

License

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