3 Get Started: Configuration
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
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
3.1 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
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 15.4.3 for more information.
After completing these steps, the
prod-cran repository will be available in
the web interface.
3.2 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.
3.3 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 # Add a Git endpoint, configured to surface tagged commits: rspm add --git-url=https://bitbucket.example.com/r-pkg.git --source=prod-internal-src --git-build-trigger=tags # Create a repository and subscribe it to the source: rspm create repo --name=prod --description='Stable releases of our internal packages' rspm subscribe --source=prod-internal-src --repo=prod
Packages can be built using Git endpoints accessed via HTTP(s) or SSH URLs -
firstname.lastname@example.org:user/repo.git. If the
Git URL uses SSH it will require an SSH key for authentication. In this case,
first import the key and then use the
SSH keys must NOT use a passphrase.
# Import the SSH key: rspm import --name=read-r-pkg --path=/path/to/ssh/key # Optionally, remove the key from disk: # rm /path/to/ssh/key # Add the package: rspm add --email@example.com/r-pkg.git --source=prod-internal-src --git-build-trigger=tags --git-ssh-key=read-r-pkg
3.4 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 15.3.2 for details on how conflicts are resolved.
3.5 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
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
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.
3.6 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,
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
update command. (Note that the latest data will depend on the server’s
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
update will use.
3.7 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.
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 15.3.2 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