Skip to content

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 how 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. RStudio 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.

Installing R#

We recommend installing multiple versions of R. An environment with multiple versions of R helps you provide a stable, reproducible environment for your R developers.

Install R using the directions at https://docs.rstudio.com/resources/install-r/.

Upgrading R#

RStudio Connect supports running multiple versions of R. We strongly recommend supporting multiple versions of R instead of upgrading and maintaining a single version of R. A system supporting multiple versions of R is the best way to ensure that your R content will continue to run.

As new versions of R are released, install the new version of R alongside previous releases.

When installing a new version of R:

  1. Stop RStudio Connect

  2. Install a new version of R; follow the directions at https://docs.rstudio.com/resources/install-r/

  3. Start RStudio Connect

You may need to configure Server.RVersion if your RStudio Connect configuration does not automatically detect this new version of R. The R Versions section describes auto-discovery and explicitly configuring an R installation.

Upgrading R in Place#

When you use the version of R that ships with your Linux distribution, an update will overwrite the old version of R with a new one. The old version of R is no longer available. This change is highly disruptive to content hosted by RStudio Connect, as the R packages required by that content need to be reinstalled for the new version of R.

Note

In-place updates can happen with custom R installations but are most common when using R from your Linux distribution. We recommend installing R into a version-specific directory, such as /opt/R/3.5.3.

R packages are rebuilt on-demand when the original version of R is no longer available. For example, the next execution of a scheduled R Markdown document will automatically trigger a rebuild and reinstall of its required packages before rendering the report. Shiny applications and Plumber APIs will see package rebuild and reinstall the first time the application is requested.

Rebuilding and restoring packages can take a significant amount of time and may delay or prevent the rendering of a report or the availability of applications. Users of Shiny applications receive a message indicating that the content will be available after packages are successfully built and installed for the new version of R.

Note

Not all packages are compatible with newer versions of R. Your R code may also be sensitive to a change in R version. R content may fail to run after an upgrade to R.

You can avoid in-place upgrades to R by installing multiple, side-by-side versions of R.

Install R using the directions at https://docs.rstudio.com/resources/install-r/.

We do not recommend using the version of R made available by your Linux distribution.

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.

Scanning#

RStudio Connect can automatically scan for R in some well-known locations.

RStudio Connect scans each of the following directories to determine if they contain a full, single-version installation:

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

Each of these locations that contains an R installation will be available for use within RStudio Connect.

Connect also scans directories that often contain multiple R installations:

/opt/R
/opt/local/R

Any child directory that contains an R installation will be available for use within RStudio Connect.

Note

Use the Server.RVersion setting to explicitly enumerate R installations if your organization uses a complicated directory hierarchy.

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/R/3.4.2-optimized-build
/opt/local/R/3.3.1

Note

Symbolic links from any of these scan locations to alternate locations are permitted.

R version scanning happens by default. Disable version scanning with the Server.RVersionScanning property.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
RVersionScanning = false

Direct Configuration#

RStudio Connect can be instructed to use specific R installations through direct R version configuration.

Direct configuration can be used in combination with scanning to add R installations that are outside the scanned locations. It is most commonly used when R version scanning is disabled - giving complete control over the permitted R versions

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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
RVersion = /shared/R/3.3.1
RVersion = /shared/R/3.2.4
RVersion = /shared/R/3.1.3

Note

The Server.RVersion property is permitted to be a symbolic link to an R installation.

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
RVersionScanning = false
RVersion = /opt/R/3.3.1
RVersion = /opt/R/3.2.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.

Copyright © RStudio, PBC. All Rights Reserved