Getting Started: Configuration – Posit Support

This article is derived from the RStudio Package Manager administration guide.

RStudio Package Manager organizes and centralizes R packages across your team, department, or entire organization.

These guides are designed to help administrators configure RStudio Package Manager for common scenarios. Before beginning, follow the Getting Started with Installation steps to install and license RStudio Package Manager.

The commands in the quick start guides need to be run as an appropriately privileged user. By default, the user should be a member of the rstudio-pm group. In addition, the instructions assume you’ve setup an alias: alias rspm='/opt/rstudio-pm/bin/rspm' or have added the binary to your path.

Once you are done setting up RStudio Package Manager, share the URL to RStudio Package Manager with users. Users will be able to setup R or RStudio to use RStudio Package Manager by following the instructions included in each repository’s Setup page.

If you prefer, you can configure RStudio Server (Pro) to use RStudio Package Manager without requiring user setup, see the configuration instructions.

Pick the quick start guide(s) most suited to your use case(s):

Serving CRAN Packages 3.1
Serving Local Packages 3.2
Serving Local Packages from Git 3.3
Serving CRAN and Local Packages 3.4
Supplementing CRAN with Bleeding Edge Packages from GitHub 3.5
Serving an Approved Subset of CRAN 3.6
Serving an Approved Subset of CRAN and Local Packages 3.7

Serving CRAN Packages

A common use case for RStudio Package Manager is making CRAN packages available in environments with restricted internet access. To do so, start by ensuring that RStudio Package Manager has the appropriate metadata using the sync command. RStudio Package Manager pulls packages and metadata from the RStudio CRAN service, it is not necessary to configure an upstream CRAN URL. Then, create a repository and subscribe it to the built-in source named “cran”.

# Initiate a sync:
rspm sync --wait

# Create a repository: 
rspm create repo --name=prod-cran --description='Access CRAN packages' 

# Subscribe the repository to the cran source:
rspm subscribe --repo=prod-cran --source=cran

The behavior of the repository will depend on the whether your server is set up for lazy or eager downloading. This choice is made in the RStudio Package Manager config file. Likewise, future updates will occur on a schedule dictated in the configuration file. See Updates from CRAN for more information.

After completing these steps, the prod-cran repository will be available in the web interface.

Distributing Local Packages

Many teams have a handful of internally built packages. If your internal packages are tracked in Git, see the next section. Otherwise, create the bundled version of each package and copy the resulting tar files to the RStudio Package Manager server. If you are unfamiliar with building the bundled version of a package, reach out to the R developer maintaining the package.

# Create a local source: 
rspm create source --name=prod-internal-src

# Add each local package tar file to the source: 
#  The tar file must be rwx by the user running the CLI and the account running
#  RSPM (rstudio-pm by default)
rspm add --source=prod-internal-src --path='/path/to/package_1.0.tar.gz'

# Create a repository: 
rspm create repo --name=prod-internal --description='Stable releases of our internal packages'

# Subscribe the repository to the source: 
rspm subscribe --repo=prod-internal --source=prod-internal-src

RStudio Package Manager automatically supports multiple versions of each package. When the R developers are ready for the next release of a package, simply run:

rspm add --source=prod-internal-src --path='/path/to/package_2.0.tar.gz'

RStudio Package Manager will ensure that version 2.0 is the default for new installations, but will keep version 1.0 available in the repository’s archive for users who wish to use the older version.

Most internal packages will depend on packages from CRAN. In this case, the easiest option is to create a repository that includes the local packages and their dependencies.

See the quickstart sections for serving local packages and all of CRAN or serving local packages and a curated subset of CRAN.

Serving Local Packages from Git

The previous configuration using a local source requires manual steps to add and update packages. If your organization uses Git to store internal R packages, you can automate this process uisng a git source.

git sources require a valid R installation.

# Create a git source:
rspm create source --type=git --name=prod-internal-src

# Create a Git builder, configured to surface tagged commits:
rspm create git-builder --url=https://bitbucket.example.com/r-pkg.git --source=prod-internal-src --build-trigger=tags

# Create a repository and subscribe it to the source:
rspm create repo --name=prod-git --description='Stable releases of our internal packages'
rspm subscribe --source=prod-internal-src --repo=prod-git

If the Git URL uses SSH, then it requires an SSH key for authentication. In this case, import the key before using the create command. SSH keys are not required to use a passphrase, but a secure key with passphrase is recommended.

# Import the SSH key:
rspm import --name=read-r-pkg --path=/path/to/ssh/key --passphrase-path=/path/to/passphrase/file

# Optionally, remove the key from disk:
# rm /path/to/ssh/key

# Add the package: 
rspm create git-builder --url=user@bitbucket.example.com/r-pkg.git --source=prod-internal-src --build-trigger=tags --ssh-key=read-r-pkg

Distributing Local Packages along with CRAN Packages

Often, for convenience, organizations opt to distribute their local packages along with CRAN packages in a single repository. This setup gives a single URL for all the organization’s R packages. To do so, follow the quick start guides above to create a local source or a git source along with a cran source, then:

# Confirm sources exist: 
rspm list sources; # should have: prod-internal-src, cran

# Create repository: 
rspm create repo --name=prod --description='Production R packages from CRAN and our local packages'

# Subscribe the repository to the sources: 
rspm subscribe --repo=prod --source=prod-internal-src; rspm subscribe --repo=prod --source=cran

In the final step, the order of subscriptions is important. Packages from the local source will be favored if there are conflicts. See Repositories with Multiple Sources for details on how conflicts are resolved.

Supplementing CRAN with Bleeding Edge Packages from GitHub

In addition to a production repository, some organizations allow advanced R users to access “bleeding-edge” versions of packages available on GitHub.

# Create a git source:
rspm create source --type=git --name=github

# Add the GitHub version of ggplot2:
rspm add --source=github --git-url=https://github.com/tidyverse/ggplot2.git --git-build-trigger=commits

# Sync CRAN:
rspm sync --wait

# Create a repository, and subscribe it to the GitHub source and CRAN:
rspm create repo --name=bleeding-edge --descrption='CRAN supplemented with bleeding edge packages from GitHub, not for production use!'
rspm subscribe --repo=bleeding-edge --source=github
rspm subscribe --repo=bleeding-edge --source=cran

The result of these steps is a repository that contains the GitHub version of the package in addition to CRAN packages. The GitHub package is installed from RStudio Package Manager using install.packages NOT devtools.

In the example above, the ordering of the source subscriptions is important. Imagine the desired GitHub package is ggplot2. ggplot2 will be available from the cran source and the git source. When ggplot2 is requested, RStudio Package Manager looks in the order of the subscriptions. First it will look for ggplot2 in the github source. Since ggplot2 is in the set of bleeding edge packages, RStudio Package Manager will find ggplot2 in the github source and serve the bleeding edge version to users. Any ggplot2 dependencies that are not in the github source will be pulled from cran. RStudio Package Manager displays whether the package came from CRAN or an alternative source in the package page for the repository.

Serving a Subset of Approved CRAN Packages

Some organizations only want to give access to an approved list of CRAN packages. A curated CRAN source enables administrators to serve the approved list of packages as well as any dependencies, while enabling admins to preview changes, add new packages, and run updates.

Create a file containing one package name per line. For example, /tmp/packages.csv:

plumber
shiny
ISLR

Start by creating a curated-cran source. Then use the add command to preview the changes needed to add the packages.

# Ensure you have CRAN metadata:
rspm sync --wait

# Create the curated-cran source:
rspm create source --name=subset --type=curated-cran

# Dry run to see proposed packages:
rspm add --file-in='/tmp/packages.csv' --source=subset --dryrun

The result will contain information on all the packages that will be added. The proposal can be saved to a csv file using the csv-out flag. The required dependencies for the named packages are automatically discovered and included. Optionally use the --include-suggests flag to also discover and add suggested packages.

This action will add the following packages:

Name        Version  Path License                   Needs Compilation Dependency
BH          1.66.0-1      BSL-1.0                   false             true
crayon      1.3.4         MIT + file LICENSE        false             true
digest      0.6.15        GPL (>= 2)                false             true
htmltools   0.3.6         GPL (>= 2)                false             true
httpuv      1.4.3         GPL (>= 2) | file LICENSE false             true
ISLR        1.2           GPL-2                     false             false
jsonlite    1.5           MIT + file LICENSE        false             true
later       0.7.3         GPL (>= 2)                false             true
...         ...           ...                        ...               ...

To complete this operation, execute this command without the --dryrun flag.
You will need to include the --transaction-id=281 flag.

If the proposal is acceptable, run the command again, but use the transaction-id indicated in the dry run output. Finally, create a repository and subscribe the repository to the source.

# Commit the changes:
rspm add --file-in='/tmp/packages.csv' --source=subset --transaction-id=281

# Create a repository:
rspm create repo --name=approved-cran --description='Approved packages from CRAN'

# Subscribe the repository to the source:
rspm subscribe --repo=approved-cran --source=subset

When the source is created, RStudio Package Manager automatically pins the “subset” source to a frozen point in time on CRAN. New packages can be added from this frozen snapshot of CRAN by repeating the process.

To update the entire set of packages to the latest data available from CRAN, use the updatecommand. (Note that the latest data will depend on the server’s sync schedule).

rspm update --source=subset --dryrun

# Like the add command, a preview of the changes is printed out
# along with a transaction-id. Use this id to commit the changes

rspm update --source=subset --transaction-id=281

Please review the full description of curated CRAN sources to understand further which points in time add and update will use.

Serving a Subset of Approved CRAN Packages and Local Packages

An extension of the previous use case is serving a subset of CRAN and a set of internal packages from within a single repository. Start by following the steps to create a source with the subset of approved packages and a local source with the desired internal packages.

Next, for each internal package, obtain the list of the package’s dependencies from the package developer. Create a csv file with one line per package name, e.g. internal_deps.csv:

xml2
jsonlite

Use the add command to add these additional dependencies to the curated CRAN source.

# List sources, should include 
# prod-internal-source and subset:
rspm list sources

# Add the local packages' dependencies:
rspm add --source=subset --file-in='internal_deps.csv' --dryrun

# Proposed changes will be printed out, to commit the changes
# run the command again with the transaction-id:
rspm add --source=subset --file-in='internal_deps.csv' --transaction-id=283

Finally, create a repository and subscribe the repository to both sources. The order of the subscription commands is important, see Repositories with Multiple Sources for details.

# Create a repo:
rspm add repo=prod-pkgs --description='Stable release of our internal packages and approved CRAN packages'

# Subscribe the repo to both sources:
rspm subscribe --repo=prod-pkgs --source=prod-internal-source
rpsm subscribe --repo=prod-pkgs --source=subset