R Package Management
Package installation
Posit Connect installs the R package dependencies of R-based content when that content is deployed. This includes Shiny applications, Plumber APIs, R Markdown documents, and Quarto projects that use R.
The RStudio IDE uses the rsconnect and renv R packages to identify the target source code and enumerate its dependencies. Source code is bundled into an archive (.tar.gz
) file and uploaded to Posit Connect. In addition to the source, the bundle lists the requirements needed to run the content, such as the version of R and the versions of R packages used by the content.
When your content uses renv and an renv.lock
is included in the deployment, the lock file is used to enumerate the required R package dependencies. When your content does not use renv or an renv.lock
is not included in the deployment, the content is analyzed to discover what packages are needed; the version of each package is determined by inspecting your active R library.
Prior to rsconnect-1.0.0, the packrat R package was used to analyze the content and discover its R package requirements. An renv.lock
was ignored.
Posit Connect receives a bundle archive (.tar.gz
) file, unpacks it, and uses packrat to install the identified package dependencies.
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.
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 thePATH
; - 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 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 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.
In rare situations, systems maintenance requires you to clear the package caches. See the Runtime Caches section for details and instructions.
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
Posit Package Manager URL rewriting
Posit Package Manager can serve R packages as source or precompiled binary. Precompiled binaries install much faster, but are only compatible with the Linux distribution for which they were compiled. For more detail, see Posit Package Manager documentation on Binary Packages and Using Linux Binary Packages.
Package Manager URL rewriting only applies to Posit Package Manager URLs. Other R package repositories (e.g. vanilla CRAN mirrors, Bioconductor, Artifactory, or filesystem repositories) are not affected.
The type of package served by Posit Package Manager is determined by the URL. For instance, https://packagemanager.posit.co/cran/latest
serves source packages, while https://packagemanager.posit.co/cran/__linux__/jammy/latest
serves binary packages for Ubuntu 22.04.
Use the setting R.PositPackageManagerURLRewriting
to control how Connect downloads packages from a Posit Package Manager instance. This setting affects both repositories configured on Connect using RPackageRepository
, and arbitrary repository URLs in published content.
The R.PositPackageManagerURLRewriting
setting takes one of four values:
auto
(default): Incompatible Posit Package Manager binary URLs will be rewritten to use compatible binaries, if they are served by the Package Manager instance. Otherwise, they will be rewritten to use source packages. Source package URLs, compatible binary URLs, and other repository URLs are unmodified.force-source
: All Posit Package Manager URLs are rewritten to use source packages.force-binary
: All Posit Package Manager URLs are rewritten to use binary packages, assuming they are served by the Package Manager instance. Otherwise, they are rewritten to use source packages.none
: Disables all rewriting of Posit Package Manager URLs. Use of this value is not recommended.
Example
With the default behavior (R.PositPackageManagerURLRewriting = auto
), Posit Connect rewrites incompatible Posit Package Manager binary URLs and leaves all other URLs unmodified. For example, on Ubuntu 22.04 (Jammy):
https://packagemanager.posit.co/cran/latest
is unmodified, because it installs source packages.https://packagemanager.posit.co/cran/__linux__/jammy/latest
is unmodified, because it installs compatible binary packages.https://packagemanager.posit.co/cran/__linux__/focal/latest
is rewritten tohttps://packagemanager.posit.co/cran/__linux__/jammy/latest
, because it installs binary packages compiled for a different version of Ubuntu.
To rewrite all URLs to install source packages, use:
; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
PositPackageManagerURLRewriting = force-source
To rewrite all URLs to install compatible binaries:
; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
PositPackageManagerURLRewriting = force-binary
External package installation
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 certain R packages should not be installed and managed by Connect and packrat. These packages must be contained in the R library for each installed version of R. Use the R.External
setting to enumerate R packages that should not be managed by Connect.
For example, rJava
or ROracle
are large installations, potentially with complex, external 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
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.
You can host private packages in a privately-hosted R package repository (a server such as CRAN that R uses to download packages). Repositories are configured in R on publishers’ computers and packages are installed normally.
Publishers can install R packages from private Git repositories hosted on GitHub, GitLab, or Bitbucket that are visible to Connect’s configured Git accounts.
From private R package repositories
Most public packages will come from a public CRAN mirror, but Posit Connect uses packrat to support additional, alternate repositories, these repositories may contain private packages. Publishers configure repositories locally on their computers. When content is deployed, its package dependencies are recorded, including details about how a package was obtained.
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.
Internally developed packages are made available through a corporate repository. This is used in combination with a public CRAN mirror.
All packages (private and public) are approved before use and must be obtained through the corporate repository. Public CRAN mirrors are not used.
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 can override the set of repositories that were used during development.
Repository information is configured using the R repos
option. Have your developers configure their R sessions to use your corporate repository.
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.
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({
<- getOption("repos")
r "CRAN"] <- "https://cran.rstudio.com/"
r["mycompany"] <- "http://rpackages.mycompany.com/"
r[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 the Git credentials from the Connect configuration to download R packages from private Git repositories that are hosted on GitHub, GitLab, and Bitbucket.
Note that packrat does not support instances of these Git providers hosted at URLs other than github.com, gitlab.com, and bitbucket.com.
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:
::install_github("mycompany/mypackage") remotes
When deploying content that uses this package, details about the GitHub package location are included. Posit Connect will obtain the same version of the package from GitHub when building an environment for your content.