.libPaths() ordering and immutable site library for staged package rollout

Answer to the Question

1. Permission boundary – The site library must be owned by a privileged group (e.g., root or a dedicated admin group) and have read‑only permissions (typically 0555). Application users run under a non‑privileged account that can read but not write to this tree. This guarantees that, even if R_LIBS_USER or a .Rprofile points to the site library, no write can occur.

2. Enforcing the intended order – Set the environment variable R_LIBS_SITE to the immutable site library path before any R process starts. This establishes the first entry of .libPaths() and is respected by all startup scripts. Then add the candidate tree as the new first entry:

# In a startup wrapper or a minimal .Rprofile placed in the app working directory
Sys.setenv(R_LIBS_SITE = "/opt/r/site")          # immutable site library
Sys.setenv(R_LIBS_USER = "/opt/r/candidate")      # candidate tree
.libPaths(c(Sys.getenv("R_LIBS_USER"), Sys.getenv("R_LIBS_SITE")))

Because R_LIBS_SITE is consulted before R_LIBS_USER, the candidate tree will always be searched first. A minimal .Rprofile that only sets .libPaths() ensures that no other startup script can reorder the search path.

3. Immutability of the first entry – The first entry (the site library) should be treated as immutable during the rollout. Mutating it in place risks exposing partially installed packages to new sessions. If the site library must be updated, do so in a separate, controlled step *after* the rollout is complete.

Practical Verification Steps

1. Check permissions – On the host, run:

   ls -ld /opt/r/site
   # Expected output: dr-xr-xr-x  ...  /opt/r/site
   

2. Verify order in a fresh session – Start R with the environment variables set and run:

   cat(.libPaths())
   # Expected: first element is /opt/r/candidate, second is /opt/r/site
   

3. Test loading the candidate package – In the same session:

   library(myPackage, character.only = TRUE)
   sessionInfo()$otherPkgs
   # Confirm the path shown matches /opt/r/candidate
   

4. Confirm write protection – As the application user, attempt to create a file in the site library:

   touch /opt/r/site/tmp.txt
   # Should return Permission denied.
   

5. After rollout – Remove the candidate tree from .libPaths() and optionally delete the directory to avoid ambiguity for future sessions.

Potential Pitfalls and Mitigations

• If the application’s working directory contains an existing .Rprofile that modifies .libPaths(), it can silently override the intended order. Sanitize or replace that file with the minimal script shown above.
• Concurrent R sessions started before the environment variables are set will keep the old .libPaths() order. Restart any long‑running workers after updating the environment.
• Ensure the candidate tree is readable by the application user; otherwise library() will fail with “cannot open shared object file” errors.

Missing Diagnostic Detail Needed?

If you have a different user group or a non‑standard site library location, let us know so we can adjust the permission and environment variable recommendations accordingly.