Configuring Posit Workbench to use Package Manager

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.

R Repositories

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:

    /etc/rstudio/repos.conf
    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 the RStudio IDE’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:

/etc/rstudio/rsession.conf
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:

    Terminal
    $ R RHOME
/opt/R/4.4.3/lib/R

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

    Create the R_HOME/etc/Rprofile.site file if it does not already exist.

  2. Navigate to the Setup page of your Bioconductor repository in the Package Manager UI. Follow the instructions, and add the repository setup code to the R_HOME/etc/Rprofile.site file.

    R_HOME/etc/Rprofile.site
    # Configure BiocManager to use Posit Package Manager
options(BioC_mirror = "https://[package-manager-server-address]/[bioconductor-repo-name]/latest")

# Configure BiocManager to load its configuration from Package Manager
options(BIOCONDUCTOR_CONFIG_FILE = "https://[package-manager-server-address]/[bioconductor-repo-name]/latest/config.yaml")

# Set the Bioconductor version to prevent defaulting to a newer version
Sys.setenv("R_BIOC_VERSION" = "[bioconductor-version]")

# Configure a CRAN snapshot compatible with Bioconductor [bioconductor-version]
options(repos = c(CRAN = "https://[package-manager-server-address]/[cran-repo-name]/[snapshot]"))

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

Authenticated R repositories

If any of your R repositories require authentication, you can configure credentials for all Workbench users by creating a netrc file and setting curl as the download method in R.

This method is widely supported and provides a secure way to access authenticated repositories in R. It works with various tools and IDEs, including install.packages(), devtools, rsconnect, renv, BiocManager, pak, RStudio Pro, and Positron Pro.

Some tools, such as renv and BiocManager, require additional configuration to use the netrc file and curl for authentication. Others, like pak, support alternative authentication methods, such as using the system keyring service.

Alternatively, users can configure credentials individually by following the instructions in the Authenticated R Repositories section of the User Guide.

Getting a token

You can create a token to use for repository authentication with the rspm create token CLI command. Refer to Creating API Tokens for details.

Note

netrc files only support configuring a single set of credentials per server. This means that if you have multiple repositories, you need to use the same token for all of them. Ensure that the token has access to each repository.

Configure R to use netrc and curl

  1. Create a netrc file in a location that is accessible to all users, such as /etc/netrc.

    Add the following content, replacing [packagemanager.example.com] with your Package Manager server address and [your-token] with your actual token.

    /etc/netrc
    machine [packagemanager.example.com]
login __token__
password [your-token]

    The machine field should not contain a protocol, port, or repository path. If your repository URL is https://packagemanager.example.com/cran/latest, use packagemanager.example.com for the machine field.

  2. Find the location of the side-wide R startup file (Rprofile.site) 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:

    Terminal
    $ R RHOME
/opt/R/4.4.3/lib/R

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

    Create the R_HOME/etc/Rprofile.site file if it does not already exist.

  3. Configure R to use curl as the download method by adding the following lines to Rprofile.site.

    Rprofile.site
    # Use curl with a netrc file for authenticated repo access
options(download.file.method = "curl")

options(download.file.extra = paste(
  "--netrc-file /etc/netrc",
  # Follow redirects, show errors, and display the HTTP status and URL
  '-fsSL -w "%{stderr}curl: HTTP %{http_code} %{url_effective}\n"',
  # Configure the user agent header to install Linux binary packages
  sprintf('--header "User-Agent: R (%s)"', paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"]))
))

    On Linux, you will need additional configuration to install Linux binary packages with curl, so that is also included here.

Additional configuration for renv, BiocManager, and pak

If any users use the renv package to manage R projects, you can configure renv to use credentials from the netrc file when installing packages. After configuring R to use netrc and curl, add the following line to the R startup file (Rprofile.site).

Rprofile.site
# Configure renv to install from authenticated repos
Sys.setenv(RENV_DOWNLOAD_METHOD = "curl")

To install packages from an authenticated Bioconductor repository, ensure you have BiocManager version 1.30.24 or later.

Once updated, follow the Setup page instructions in the Package Manager UI to configure the Bioconductor mirror for Workbench.

If any users use the pak package to install R packages, you can configure pak to use credentials from either the netrc file or system keyring service. These features are only available in latest development version of pak.

If you are exclusively using pak for package installation, we recommend using the system keyring as a more secure option for storing credentials than .netrc. However, this method may require user interaction and may not work in all scenarios.

For details, refer to the pak documentation on Configuring authenticated repositories. For instructions on installing the development version of pak, refer to the pak documentation on Nightly builds.

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.

Note

Some Ubuntu and Debian R binaries (installed via apt-get install) include an Rprofile.site file that modifies the repository option. Unless you intended to have this file, we recommend removing /usr/lib/R/etc/Rprofile.site.

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

If you changed any R startup files (e.g., ~/.Rprofile), restart your R session to apply the changes. Note that in RStudio Pro, closing and reopening the browser tab or clicking the reload button will not start a new R session.

For CRAN or internal package repositories, running getOption("repos") in R should show the URL of the Package Manager instance. For Bioconductor repositories, running getOption("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:

R
# Show the configured repos
getOption("repos")

# Install a package in the repository, such as A3
install.packages("A3")

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 repository, you can download and install a Bioconductor package:

R
# Show the configured Bioconductor repo
getOption("BioC_mirror")

# 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)

Python Repositories

These instructions assume you’re using pip for installing packages. Other tools may use the same index URL in their configuration.

Tip

The pip command may differ depending on your local python installation. If the pip command is not found, try the pip3 command instead.

You can set package installation options for pip to install Python packages by creating or modifying the /etc/pip.conf file. For more information about configuring pip, refer to the pip documentation User Guide.

Specifying a Package Repository

You can configure Posit Workbench to use a Package Manager repository when installing packages via pip.

For example, to configure the public Posit Package Manager as the repository with a timeout of 60 seconds, add the following to /etc/pip.conf:

/etc/pip.conf
[global]
timeout = 60
index-url = https://packagemanager.posit.co/pypi/latest/simple
trusted-host = packagemanager.posit.co

Setting index-url replaces pip’s default repository (PyPI). To add a new repository, use the extra-index-url setting.

Authenticated Python Repositories

If any of your Python repositories require authentication, you can configure credentials for all Workbench users by creating a netrc file.

This method is widely supported and provides a secure way to access authenticated repositories in Python. It can be used with various tools, including pip.

Alternatively, users can configure credentials individually by following the instructions in the Configure Python authenticated repositories section of the User Guide.

Getting a token

You can create a token to use for repository authentication using the rspm create token CLI command. Refer to Creating API Tokens for details.

Note

netrc files only support configuring a single set of credentials per server. This means that if you have multiple repositories, you need to use the same token for all of them. Ensure that the token has access to each repository.

Configure Python to use netrc

  1. Create a netrc file in a location that is accessible to all users, such as /etc/netrc.

    Add the following content, replacing [packagemanager.example.com] with your Package Manager server address and [your-token] with your actual token.

    /etc/netrc
    machine [packagemanager.example.com]
login __token__
password [your-token]

    The machine field should not contain a protocol, port, or repository path. If your repository URL is https://packagemanager.example.com/pypi/latest, use packagemanager.example.com for the machine field.

  2. Create a profile script at /etc/profile.d/netrc.sh with the following content.

    /etc/profile.d/netrc.sh
    export NETRC=/etc/netrc

  3. Add the following lines to /etc/pip.conf, replacing packagemanager.example.com with your Package Manager server address.

    /etc/pip.conf
    [global]
timeout = 60
index-url = https://packagemanager.example.com/pypi/latest/simple
trusted-host = packagemanager.example.com
Back to top