14 R

RStudio Connect offers a flexible way of deploying your Shiny applications, Plumber APIs, and R Markdown content against a variety of R versions.

A compatible version of R is identified when content is deployed. That R installation is used any time R is needed for that content. Package installation, starting a Shiny application or Plumber API, and rendering R Markdown documents will all use the version of R discovered at deploy-time.

RStudio Connect allows different content to rely on different versions of R. For example, Alice’s R Markdown document may require version 3.2.4 of R while Bob’s Shiny application needs R version 3.3.1. Those two deployments using different R versions can coexist in RStudio Connect without conflict.

This chapter discusses RStudio Connect can be configured to support more than one version of R and how R version compatibility is determined.

Available R installations are analyzed at startup. Connect logs the discovered R versions. Connect will fail to start if no R installation can be found.

Changing any of the configuration items discussed in this chapter requires a restart of RStudio Connect.

14.1 Installing R

Ubuntu and Red Hat/CentOS Linux distributions offer a version of R; installation of the system R is detailed in sections 2.1.1 and 2.1.2.

If you are attempting to make additional R versions available side-by-side with the system version you typically need to install from source. The RStudio Server documentation has a good reference for building and installing R into alternate locations.

This RStudio Support article also includes R installation instructions.

14.2 Upgrading R

RStudio Connect supports running multiple versions of R. In most cases, upgrading R should consist of building the new version of R and retaining the previous version. We strongly recommend supporting multiple versions of R instead of upgrading and maintaining a single version of R. Supporting multiple versions of R is the best way to ensure applications or reports published with specific package dependencies will continue to run.

In cases where a single version of R is being managed, R can be upgraded using the system package manager with the following steps:

  1. Stop RStudio Connect, see 5.1
  2. Follow the instructions to upgrade R.

    For Ubuntu, be sure an up-to-date CRAN repo is in the source list, and then run:

    $ sudo apt-get update
    $ sudo apt-get install r-base --upgrade

    For RedHat/CentOS:

    $sudo yum update R
  3. Start RStudio Connect

Following an upgrade, content dependent on R will be rebuilt on-demand. For example, during the next execution of a scheduled R Markdown document, Connect will automatically reinstall and rebuild all of the necessary packages before rendering the report. For Shiny applications and Plumber APIs, the reinstall and rebuild will occur the first time the application is requested. During the package updates, Connect will present a message and spinner indicating to the end user that the Shiny application will be available after the packages are successfully installed and built for the new version of R.

Not all packages can be reinstalled and rebuilt on newer versions of R. Rebuilding and restoring packages can take a significant amount of time and could delay or prevent the rendering of a report or the availability of a Shiny application.

14.3 R Versions

RStudio Connect supports two ways of discovering R versions: scanning well-known locations and through direct configuration. Connect will use the PATH environment variable to discover a version of R if one is not otherwise found.

14.3.1 Scanning

RStudio Connect can automatically scan for versions of R in the following locations:

/usr/lib/R
/usr/lib64/R
/usr/local/lib/R
/usr/local/lib64/R
/opt/local/lib/R
/opt/local/lib64/R

In addition, Connect scans all subdirectories of the following directories within /opt:

/opt/R
/opt/local/R

For example, any of the following installed versions of R will be automatically detected:

/opt/R/3.1.3
/opt/R/3.2.4
/opt/local/R/3.3.1

Scanning happens by default. You can disable version scanning by customizing the Server.RVersionScanning property.

[Server]
RVersionScanning = false

14.3.2 R Versions

The Server.RVersion property can be used to specify alternate locations for installations of R. Specify this property once for each R installation directory.

[Server]
RVersion = /shared/R/3.3.1
RVersion = /shared/R/3.2.4
RVersion = /shared/R/3.1.3

14.3.3 /etc/rstudio/r-versions

The /etc/rstudio/r-versions file is an alternative way of specifying R versions and is shared with RStudio Server. List your R installations in this file. Note that the r-versions file is not created by default and will need to be created.

/shared/R/3.3.1
/shared/R/3.2.4
/shared/R/3.1.3

14.3.4 Excluding Versions

If you have versions of R that are picked up by automatic scanning but which you would like to exclude, disable R version scanning and explicitly specify all versions you would like to use in the /etc/rstudio/r-versions file or with the Server.RVersion configuration property.

Here is an example configuration that disables scanning, and specifies precisely two R versions that will be available for use.

[Server]
RVersionScanning = false
RVersion = /opt/R/3.3.1
RVersion = /opt/R/3.2.4

14.4 R Version Matching

RStudio Connect attempts to find an R installation that is appropriate for your content. By default, it applies a “nearest” matching approach. This algorithm attempts to always find a version of R to use with your content. More deployments will succeed but not always with the same version of R that is used by the author.

If you would prefer a strict association between authored and deployed R versions, you can choose to use an “exact” matching approach.

The “nearest” matching algorithm is the most flexible option and favors publication of your content over precise duplication of the authoring environment.

The “major-minor” algorithm is a middle ground between “nearest” and “exact”. It requires exact MAJOR.MINOR matching but is flexible about the patch level. This is a useful option when your desktop and server may occasionally have different update cycles when installing bug fix releases.

An inconsistent version of R occasionally causes problems when installing package dependencies. For the best results, make sure that RStudio Connect has access to the same versions of R used to author content.

The R version matching approach is controlled with the Server.RVersionMatching configuration setting.

nearest

Find an R installation that is close to the version of R used when authoring the Shiny application, Plumber API, or R Markdown document. This algorithm uses the ordered tests when looking for MAJOR.MINOR.PATCH version matches:

  1. Use exact version match.
  2. If there are matching MAJOR.MINOR releases, use least-greater version.
  3. If there are matching MAJOR.MINOR releases, use latest of these.
  4. Use least-greater version across all releases.
  5. Use latest across all releases.
major-minor

Find an R installation that is close to the version of R used when authoring the Shiny application, Plumber API, or R Markdown document requiring an exact MAJOR.MINOR version match. If a compatible version cannot be found, content will fail to deploy. The algorithm is a constrained “nearest” search:

  1. Use exact version match.
  2. If there are matching MAJOR.MINOR releases, use least-greater version.
  3. If there are matching MAJOR.MINOR releases, use latest of these.
exact

Finds an R installation that exactly matches the version of R used when authoring the deployed content. If a matching version cannot be found, content will fail to deploy.