Skip to content

R Package Management#

Package Installation#

Posit Connect installs the R package dependencies of Shiny applications, Plumber APIs, and R Markdown documents when that content is deployed.

The RStudio IDE uses the rsconnect and packrat R packages to identify the target source code and enumerate its dependencies. That information is bundled into an archive (.tar.gz) file and uploaded to Posit Connect.

Posit Connect receives a bundle archive (.tar.gz) file, unpacks it, and uses packrat to install the identified package dependencies.

Note

Posit Connect includes and manages its own installation of the packrat package. This packrat installation is not available to user code and used only when restoring execution environments.

The execution environment created by Posit Connect and packrat contains the same package versions you are using in your development environment.

Note

Packrat uses the tar command to extract downloaded packages. Packrat determines the tar binary to use with the following heuristic:

  • If a TAR environment variable is set, respect that;
  • If on Unix, look for tar on the PATH;
  • If on Windows, look for the system tar and use that if it exists;
  • Otherwise, return use R's internal tar implementation, which may encounter issues with long filenames.

Package Caching#

The packrat package attempts to re-use R packages whenever possible. The shiny package, for example, is installed when the first Shiny application is deployed. That version of shiny is placed into the packrat package cache and associated with that Shiny application deployment. Other Shiny applications built with the same version of the shiny package will use that cached installation. Deployments are faster when they can take advantage of previously-installed packages.

The packrat package cache allows multiple versions of a package to exist on a system. An old Shiny application built with shiny version 1.0.5 continues to use that package version even as newer deployments choose updated versions of shiny. Each Shiny application has an R environment with its expected shiny version. The different applications and shiny versions coexist.

Publish new content without worrying about package updates breaking existing, deployed content. Distinct versions of packages are kept isolated from each other.

Package Compilation#

Some packages contain C and C++ code components. That code needs to be compiled during package installation. The Server.CompilationConcurrency setting controls the number of concurrent compilation processes used by package installation.

This property controls the number of concurrent C/C++ compilations during R package installation. High values may encounter memory capacity issues on lightweight hosts.

You can customize Server.CompilationConcurrency to force a specific level of concurrency.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
CompilationConcurrency = 1

External Package Installation#

Warning

Adding external packages decreases the reproducibility and isolation of content on Posit Connect, and should only be done as a last resort. To use private packages with Posit Connect, see the section on Private Packages below

You can indicate that a system-wide installation of an R package should be used instead of one fetched by packrat. Use the R.External setting to enumerate system-provided R packages that should not be managed by Connect.

For example, rJava or ROracle are large installations, potentially with odd dependencies, such as your choice of JDK and/or Oracle InstantClient. Install these packages into every R installation used by Posit Connect, then configure Connect to treat those packages as external:

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
External = ROracle
External = rJava

Posit Connect will report an error during startup if some of the external R packages are missing from any configured R installation. If you are not able to install an external R package into all R installations (perhaps because that package is not compatible with some versions of R), use the R.ExternalsCheckIsFatal setting to prevent this check.

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

Note

The R.External setting uses the packrat option external.packages to indicate that certain packages are outside the project. The packrat documentation explains external.packages and its use by packrat::restore.

Proxy Configuration#

If the http_proxy and/or https_proxy environment variables are provided to Posit Connect when the server starts, those variables will be passed to all processes run by Posit Connect, including the package installation process.

Configuring Packages.HTTPProxy and Packages.HTTPSProxy will provide their values as the http_proxy and https_proxy environment variables only when packages are installed during deployment. This could be useful if you have a special proxy just for downloading package dependencies. You could regulate access to unapproved packages in non-CRAN repositories by rejecting certain URL patterns.

Private R Packages#

Most R packages in R projects are installed from public CRAN mirrors, but Posit Connect supports multiple ways of using private R packages in deployed content.

From Private R Package Repositories#

Most public packages will come from a public CRAN mirror, but Packrat lets Posit Connect support alternate repositories in addition to CRAN, which can contain private packages. Publishers configure repositories locally on their computers. When content is deployed, Packrat records details about how a package was obtained in addition to information about its dependencies.

Info

Learn how to create your own custom repository; this directory can then be shared over HTTP or through a shared filesystem.

Here are some reasons why your organization might use an alternate/private repository.

  1. Internally developed packages are made available through a corporate repository. This is used in combination with a public CRAN mirror.

  2. All packages (private and public) are approved before use and must be obtained through the corporate repository. Public CRAN mirrors are not used.

  3. Direct access to a public CRAN mirror is not permitted. A corporate repository is used as a proxy and caches public packages to avoid external network access.

Posit Connect supports private repositories when the deploying instance of R is correctly configured, with no adjustment to the Posit Connect server needed.

Sometimes the deploying instance of R and the Posit Connect server must have different repository URLs. The RPackageRepository configuration option allows repository URLs set by the user to be overridden on each packrat restore.

Repository information is configured using the repos R option. Your users will need to make sure their computer's R is configured to use your corporate repository.

Note

RStudio IDE version 0.99.1285 or greater is needed when using repositories other than the public CRAN mirrors.

We recommend using a $HOME/.Rprofile file on the deploying computer to configure multiple repositories or non-public repositories.

Note

The .Rprofile file should be created in a user's home directory. Note that .Rprofile files in content directories will not be used during package installation on Posit Connect, even if they are included in deployed files.

# A sample .Rprofile file with two different package repositories.
local({
  r <- getOption("repos")
  r["CRAN"] <- "https://cran.rstudio.com/"
  r["mycompany"] <- "http://rpackages.mycompany.com/"
  options(repos = r)
})

This .Rprofile creates a custom repos option. It instructs R to attempt package installation first from "CRAN" and then from the "mycompany" repository. R installs a package from the first repository in "repos" containing that package.

With this custom repos option, you will be able to install packages from the mycompany repository. Posit Connect will be able to install these packages as code is deployed.

For more information about the .Rprofile file, see help(Startup) in R. For details about package installation, see help(install.packages) and help(available.packages).

From Private Git Repositories#

Posit Connect and Packrat can use Connect's configured Git credentials to download R packages from private Git repositories that hosted on GitHub, GitLab, and Bitbucket.

Note

Note that Packrat does not support instances of these Git providers hosted at URLs other than github.com, gitlab.com, and bitbucket.com.

Warning

When this setting is enabled, all package downloads from GitHub, GitLab, and Bitbucket will include the credentials. If credentials are invalid, all package installations, including those from public repos, will fail.

To allow Connect to use configured Git credentials for package restore, set the R.RestoreUsesGitCredentials setting to true.

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
RestoreUsesGitCredentials = true

You must also configure Git credentials as you would to deploy content from private Git repositories. See the section on Git-backed content and refer to GitCredential in the Configuration appendix for more information. The account you configure must be able to access any Git repositories containing R packages you wish to use.

Publishers must also configure appropriate Git provider credentials on their computer. They then install the package locally using an R package like remotes. For instance, to install a package from GitHub:

remotes::install_github("mycompany/mypackage")

When deploying content that uses this package, Packrat will track where the package was obtained. On the Connect server, the package will be retrieved from the same location.

Source Package Directory#

Packages available on CRAN, a private package repository, or a public GitHub repository are automatically downloaded and built when an application is deployed. Posit Connect cannot automatically obtain packages from private GitHub repositories, but a workaround is available.

Note

We recommend using a private repository to host internal packages when possible. See the Private R Repositories section for details.

Warning

Server.SourcePackageDir is deprecated as of Posit Connect 1.8.6 and will be removed in a future version. We recommend using a private repository.

The configuration option Server.SourcePackageDir can reference a directory containing additional packages that Connect would not otherwise be able to retrieve. This directory and its contents must be readable by the Applications.RunAs user. Connect will look in this directory for packages before attempting to obtain them from a remote location.

This feature has some limitations.

  • The package must be tracked in a git repository so that each distinct version has a unique commit hash associated with it.

  • The package must have been installed from the git repository using the devtools package so that the hash is contained in the DESCRIPTION file on the client machine.

If these conditions are met, you may place .tar.gz source packages into per-package subdirectories of SourcePackageDir. The proper layout of these files is <package-name>/<full-git-hash>.tar.gz.

For example, if Server.SourcePackageDir is defined as /opt/R-packages, source bundles for the MyPrivatePkg package are located at /opt/R-packages/MyPrivatePkg. A commit hash of 28547e90d17f44f3a2b0274a2aa1ca820fd35b80 needs its source bundle stored at the following path:

/opt/R-packages/MyPrivatePkg/28547e90d17f44f3a2b0274a2aa1ca820fd35b80.tar.gz

When private package source is arranged in this manner, users of Posit Connect will be able to use those package versions in their deployed content.

Be aware that this mechanism is specific to the commit hash, so you will either need to make many git revisions of your package available in the Server.SourcePackageDir directory hierarchy or standardize to a particular git commit of the package.

Copyright © Posit Software, PBC. All Rights Reserved