Runtime Caches

Posit Connect maintains content runtime caches containing R packages and Python environments. These caches mean that most content deploys do not need to install every package dependency; the content can re-use the compatible packages installed by an earlier deployment.

This section explains how to reset your content runtime caches and when that reset may be necessary.

Cache Invalidating Operations

R and Python packages are frequently compiled and linked against the installed system libraries.

Most day-to-day administration tasks can be performed without invalidating the packages installed into the runtime caches. Distribution-managed system package updates, for example, are safe; Linux distributions ensure compatibility when issuing patches.

Major systems upgrades or updates to system libraries that are not managed by the Linux distribution can cause incompatibilities with previously built R and Python packages.

The following systems maintenance operations can cause previously built R and Python packages to become incompatible with the modified system:

  1. Rebuilding R or Python.

    Custom builds of R and Python are configured with a specific set of options and are compiled against a specific set of system libraries. Changing that compilation configuration can produce R and Python binaries that are not compatible with packages installed previous.

    For example, rebuilding R to adjust its LAPACK implementation can cause package incompatibilities.

  2. Manual system library upgrade.

    Upgrading system libraries not managed by the Linux distribution can introduce package incompatibilities.

    The GDAL libraries, for example, occasionally include breaking changes. Installing a newer GDAL version can break previously installed instances of the sf R package.

    Upgrades to the BLAS libraries, can cause incompatibilities with the numpy package.

    Prefer system libraries that are available through your Linux distribution.

  3. Compiler and build-chain upgrades.

    Making major changes to the default compiler and its build-chain can prevent the use of previously built R and Python packages.

    Prefer the compiler version that is default for your Linux distribution, or choose the target compiler during initial host provisioning.

  4. Execution environment change.

    Changes to the execution environment can invalidate previously installed R and Python packages. For example, you may transition between a bare metal, virtual machine, or containerized installation.

Use our recommended workflow to clear the Posit Connect R and Python runtime caches and rebuild your deployed content to repopulate those caches.

Prerequisites

  1. A Connect API key for an administrator account.

    You will use this API key to clear the runtime caches and optionally rebuild content.

Workflow

Important

When you clear the runtime caches, you are removing the packages required by your deployed content. That content cannot be run until it is rebuilt and its package dependencies installed. That rebuild is automatic when the content is next run, but may take some time to complete.

Note

Resetting the content runtime caches should be an infrequent activity performed only when a systems change invalidates the existing caches. Please contact Posit customer support () if you have reason to regularly take this action.

Step 1: Clear runtime caches

Use the rsconnect-python CLI to enumerate and clear the R and Python runtime caches. These caches contain packages that were built and installed using your old system configuration.

These sample delete calls act on only one cache; you may need to perform multiple deletions. See the rsconnect-python documentation for more detail on commands.

# Enumerate the caches known to your server.
rsconnect system caches list \
    --server https://connect.example.org:3939 \
    --api-key my-api-key

# Validate cache targeted for deletion.
rsconnect system caches delete \
    --server https://connect.example.org:3939 \
    --api-key my-api-key \
    --language Python \
    --version 3.9.5 \
    --image-name rstudio/content-base:r3.6.3-py3.9.5-jammy \
    --dry-run

# Delete one cache.
rsconnect system caches delete \
    --server https://connect.example.org:3939 \
    --api-key my-api-key \
    --language Python \
    --version 3.9.5 \
    --image-name rstudio/content-base:r3.6.3-py3.9.5-jammy

Step 2: Rebuild content

Use the rsconnect-python CLI to rebuild your most important content. After clearing the runtime caches, content is automatically rebuilt when it first run. A preemptive rebuild means that visitors do not experience a delayed load. The rebuild is especially useful for interactive applications and APIs.

This sample workflow enumerates and rebuilds all content. You may want to operate on a subset of deployed content or prioritize rebuilding based on the needs of your business. The rsconnect-python documentation describes other workflows, and describes the content search and content build commands in more detail.

# Enumerate every "published" content item and save its GUID.
rsconnect content search \
    --server https://connect.example.org:3939 \
    --api-key my-api-key \
    --published | jq '.[].guid' > guids.txt

# Queue each GUID for build.
xargs printf -- '-g %s\n' < guids.txt | xargs rsconnect content build add \
    --server https://connect.example.org:3939 \
    --api-key my-api-key

# Build each queued content item.
rsconnect content build run \
    --server https://connect.example.org:3939 \
    --api-key my-api-key