R

Off-Host Execution

When using off-host execution, R versions are defined by the set of Execution Environments available for executing content. For an overview of this feature, please see the Execution Environments appendix. Connect selects an appropriate image from the set of configured images based on the version of R requested by the content.

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

Posit 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 Posit Connect without conflict.

This chapter discusses how Posit 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. Posit 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 Posit Connect.

Disabling R support

R support is enabled by default but can be disabled by setting the R.Enabled property to false.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
Enabled = false

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.posit.co/resources/install-r/.

Upgrading R

Posit 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 Posit Connect

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

  3. Start Posit Connect

You may need to configure R.Executable if your Posit Connect configuration does not automatically detect this new version of R. The R Versions section describes automatic 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 Posit 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. You can proactively rebuild Python or R content using the rsconnect content build command included with the rsconnect-python Python package.

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.posit.co/resources/install-r/.

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

R versions

Posit Connect supports two ways of discovering the installed versions of R: through explicit configuration and by scanning well-known locations.

Explicit configuration

Posit Connect can be instructed to use specific R installations. The R.Executable setting indicates an installation of R that Connect should use. Specify R.Executable once for each R installation.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
Executable = /shared/R/3.3.1/bin/R
Executable = /shared/R/3.2.4/bin/R
Executable = /shared/R/3.1.3/bin/R
Note

The paths defined by R.Executable may use symbolic links. Symbolic links are resolved in order to identify the physical R installation.

While R.Executable can be used in combination with scanning, it is most commonly used when Posit Connect does not automatically scan for R installations. By using R.Executable and disabling scanning, you have complete control over the R versions in use.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
ExecutableScanning = false
Executable = /shared/R/4.2.1/bin/R
Executable = /shared/R/4.1.3/bin/R

Scanning

Posit Connect can automatically scan for R in some well-known locations using three approaches.

  • Version scanning: Looking for R in locations known to contain multiple version installations. Enabled by default.
  • System scanning: Looking for R in locations used by system package managers. Disabled by default.
  • Path scanning: Looking for R using the PATH environment variable. Disabled by default, and only occurs if an R location is not otherwise discovered or configured.

All three kinds of scanning can be prevented by disabling the R.ExecutableScanning setting. In addition, each type of scanning can be individually controlled.

The following configuration snippet shows all four scanning settings.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
ExecutableScanning = false
ExecutableVersionScanning = false
ExecutableSystemScanning = false
ExecutablePathScanning = false
Tip

Use the R.Executable setting to explicitly enumerate R installations.

R version scanning happens by default. Disable version scanning with the R.ExecutableScanning property.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
ExecutableScanning = false

Version scanning

Posit Connect can scan 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 Posit Connect.

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

/opt/R/3.1.3/bin/R
/opt/R/3.2.4/bin/R
/opt/R/3.4.2-optimized-build/bin/R
/opt/local/R/3.3.1/bin/R
Note

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

Version scanning is enabled by default and can be disabled with R.ExecutableVersionScanning. All scanning can be disabled with the R.ExecutableScanning setting.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
ExecutableVersionScanning = false
Note

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

System scanning

Posit Connect can scan 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 Posit Connect.

System scanning is disabled by default and can be enabled with R.ExecutableSystemScanning. The R.ExecutableScanning setting must also be enabled for system scanning to be allowed.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
ExecutableScanning = true
ExecutableSystemScanning = true
Warning

Use of a single, system-managed R installation is not recommended for most Posit Connect installations. An environment with multiple versions of R helps you provide a stable, reproducible environment for your R developers.

Path scanning

Posit Connect can use the PATH environment variable to discover a version of R if one is not otherwise found.

Path scanning is disabled by default and can be enabled using the R.ExecutablePathScanning setting. The R.ExecutableScanning setting must also be enabled for path scanning to be allowed.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
ExecutableScanning = true
ExecutablePathScanning = true
Warning

Use of PATH to locate a single R installation is not recommended for most Posit Connect installations. An environment with multiple versions of R helps you provide a stable, reproducible environment for your R developers.

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 R.Executable 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
[R]
ExecutableScanning = false
Executable = /opt/R/3.3.1/bin/R
Executable = /opt/R/3.2.4/bin/R

R version matching

Posit 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 Posit Connect has access to the same versions of R used to author content.

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

nearest

Find an R installation that is close to the version of R used when authoring the content. 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 with an exact MAJOR.MINOR version match that is close to the version used when authoring the content. 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 content. If a matching version cannot be found, content will fail to deploy.