Configuring Posit Workbench#

Administrators can configure Posit Workbench to automatically use Posit Package Manager when users install packages.

The necessary configuration files are documented in the Posit Workbench Administration guide, example configurations are provided here for common scenarios.

A Single Repository#

In the most common scenario, users will install all packages from a single Package Manager repository that may contain CRAN packages and internal packages. An admin can discourage users from changing this repository setting. In this scenario, configure Workbench:

1. In /etc/rstudio/rsession.conf, set:

   /etc/rstudio/rsession.conf

   r-cran-repos=https://<package-manager-server-address>/<repo-name>/latest
   

   The exact URL to use is available in the Package Manager Setup page for the repository.

2. Workbench only: To disable the repository option menu and discourage users from changing the repository setting, also include in /etc/rstudio/rsession.conf:

   /etc/rstudio/rsession.conf

   allow-r-cran-repos-edit=0
   

Internal Packages and CRAN Packages#

Another common scenario is to set up two repositories in Package Manager, one to serve CRAN packages and one to serve internal packages. (This setup also applies if you're only using Package Manager for internal packages and want to allow users to access a public CRAN mirror).

1. In /etc/rstudio/rsession.conf, remove any existing r-cran-repos configuration.
2. Create a file called /etc/rstudio/repos.conf. The file should contain:

CRAN=https://<package-manager-server-address>/<cran-repo-name>/latest
Internal=https://<package-manager-server-address>/<internal-repo-name>/latest

The name Internal can be replaced with whatever name makes sense for your organization, but the repo containing CRAN packages should be indexed with the keyword CRAN.

Allow Users to Optionally Add Additional Repos#

In addition to the two scenarios described above, some organizations may have additional repositories for certain groups of users, e.g. "bleeding edge" packages available in a dedicated "dev" repository. Administrators can configure RStudio Desktop's Global Options menu to automatically offer Package Manager repositories as optional, secondary repos that a user can opt into using.

In /etc/rstudio/rsession.conf, set:

r-cran-repos-url=https://<package-manager-server-address>/__api__/repos
allow-r-cran-repos-edit=1

Binary Packages#

Package Manager supports serving precompiled binary packages for the CRAN source, which can significantly speed up CRAN package installations.

To enable binary packages for users, follow the Configuration Steps and the R Configuration Steps for Linux, or Windows and macOS to set up your R environment. For Linux binaries, also configure Workbench to use the binary repository URLs.

Bioconductor Repositories#

Workbench can be configured to use a Bioconductor repository as the default Bioconductor mirror. Unlike CRAN repositories, the default Bioconductor mirror must be configured separately in an R startup file.

We recommend setting the default Bioconductor mirror in the site-wide R startup file (Rprofile.site), which applies to all users for a single version of R.

1. Find the location of the Rprofile.site file at R_HOME/etc/Rprofile.site. For a given version of R, R_HOME can be found by running the R RHOME command at a terminal:

$ R RHOME
<< /opt/R/4.0.3/lib/R

#  Rprofile.site is located at:
<< /opt/R/4.0.3/lib/R/etc/Rprofile.site

1. Create the R_HOME/etc/Rprofile.site file if it does not already exist.
2. In R_HOME/etc/Rprofile.site, add the repository setup code from the Setup page of a Bioconductor repository:

# Set the default Bioconductor mirror
options(BioC_mirror = "https://<package-manager-server-address>/<bioconductor-repo-name>/latest")

This may also include setup code to enable Bioconductor use in an offline environment.

For more information on configuring R startup files, see this article on managing R startup files.

Precedence of Settings#

If you have a site-wide R startup file (Rprofile.site) that modifies the repository setting, that file will take precedence over the Workbench rsession.conf and repos.conf files.

Users can still modify the repository setting for their project needs using a user or project-level .Rprofile file, which takes precedence over Rprofile.site, rsession.conf, and repos.conf.

Checking For Success#

Once edits have been made to the appropriate configuration files (see above), start a new Workbench session. Closing and reopening the browser tab or pressing the reload button on the browser does not start a new session.

At that point, running options('repos') from the Workbench console should show the URL of the Package Manager instance. If you've configured the default Bioconductor mirror, running options('BioC_mirror') should also show the URL of the Package Manager instance.

For a complete test, you can also confirm that packages are installed from the Package Manager instance by default. To test a CRAN or internal package repository, run the following commands to install a package in the repository:

# Install a package in the repository
install.packages("test-package")

# Check that the package's DESCRIPTION file includes "Repository: RSPM"
packageDescription("test-package")

While you can install any package as a test, one that is small and has few dependencies will be the quickest. The A3 package on CRAN is the first alphabetically that meets this criteria.

To test the Bioconductor mirror, you can download and install a Bioconductor package:

# Install the BiocManager package from CRAN
install.packages("BiocManager")

# Check that BiocManager uses Package Manager for the Bioconductor repositories
BiocManager::repositories()

# Install a Bioconductor package
BiocManager::install("BiocVersion", update = FALSE)

# Check that the package's DESCRIPTION file includes "Repository: RSPM"
packageDescription("BiocVersion")