posit/workbench-session repository overview

⁠

⁠Posit Workbench Session container image

These container images provide the session runtime environments for Workbench⁠ in Kubernetes. Each image bundles a specific R and Python version pair, along with Jupyter, Quarto, and Posit Professional Drivers, so that user sessions run in an environment matching the user's language requirements.

⁠Quick reference

⁠Related images

For Kubernetes deployments, Workbench uses several images together. See the repository README⁠ for Helm configuration.

⁠How to use this image

Do not run these images directly. The Workbench Job Launcher schedules them as session pods when users start sessions on Kubernetes. Each pod runs an interactive session (RStudio Pro, VS Code, Positron, or Jupyter) using the R and Python versions baked into the image. You should pick the image(s) with the R and Python versions that best match your needs, extend the image with additional libraries and packages you require, or build your own from scratch. The workbench-session-init and workbench-positron-init init containers supply the session runtime components that the session image itself does not bundle.

Configure these images as session images for Workbench through any of the following methods:

1. Helm chart values: The rstudio/rstudio-workbench Helm chart includes a default set of session images. See the repository README⁠ for configuration details.
2. Launcher configuration: Define available session images in the Workbench Job Launcher configuration. See Using Docker images with Posit Workbench, Launcher, and Kubernetes⁠.

⁠Image tags

Posit publishes images to:

• Docker Hub: docker.io/posit/workbench-session
• GitHub Container Registry: ghcr.io/posit-dev/workbench-session

Ubuntu 24.04 is the default OS. The Standard (std) variant is the default; tags without a variant suffix resolve to it.

The tag format is: R{r_version}-python{python_version}-{os}[-{variant}]

Examples:

• R4.5.2-python3.14.3-ubuntu-24.04 — R 4.5.2, Python 3.14.3, Ubuntu 24.04, standard variant
• R4.5.2-python3.14.3-ubuntu-24.04-std — Explicit standard variant
• R4.5.2-python3.14.3-ubuntu-24.04-min — Minimal variant
• R4.4.3-python3.12.12-ubuntu-22.04 — R 4.4.3, Python 3.12.12, Ubuntu 22.04, standard variant
• R4.3.3-python3.11.15-ubuntu-24.04 — R 4.3.3, Python 3.11.15, Ubuntu 24.04, standard variant

⁠Architectures

Posit publishes Ubuntu 24.04 session images for both linux/amd64 and linux/arm64. Pull the same tag from either platform. Docker selects the matching manifest automatically. Posit publishes Ubuntu 22.04 session images for linux/amd64 only.

⁠Installed software

Each image includes:

These images do not bundle the Workbench session components themselves. The workbench-session-init init container provides those components at runtime through a shared volume.

⁠Image variants

Two variants are available:

Both variants ship the same R, Python, Jupyter, Quarto, TinyTeX, and Posit Professional Drivers versions for a given tag. The Containerfiles in this repository under workbench-session/matrix/ document the exact packages installed in any tag.

See extending examples⁠ for how to build on the Minimal image.

⁠User

These images do not declare a USER. Containers start as root. The Workbench Job Launcher manages the runtime user when scheduling session pods, dropping privileges to the signed-in user as configured by the Workbench administrator.

⁠Examples

⁠Extending an image with additional R packages

Use any tag as a base for a derived image with additional dependencies. For example, an image with Tidyverse pre-installed:

FROM ghcr.io/posit-dev/workbench-session:R4.5.2-python3.14.3-ubuntu-24.04

RUN /opt/R/4.5.2/bin/R -e 'install.packages("tidyverse", repos = "https://p3m.dev/cran/__linux__/noble/latest")'

See session extending examples⁠ for additional patterns, including pre-installing Python packages and system dependencies.

⁠Migrating from legacy image

These images replace the legacy rstudio/workbench-session⁠ and rstudio/r-session-complete⁠ images. The runtime tools are unchanged. R, Python, Jupyter, Quarto, and Posit Professional Drivers install at the same paths under /opt, and Workbench schedules sessions into these images the same way. The differences are in how Posit publishes, tags, and packages the images and their session components.

⁠Image references

Posit published the legacy images as rstudio/workbench-session and rstudio/r-session-complete on Docker Hub and at the equivalent paths on GitHub Container Registry, with tags like ubuntu2204-r{R1}_{R2}-py{Py1}_{Py2} for linux/amd64 only. Update your image references to one of the replacement locations and pick a tag that pins to your desired R, Python, and OS versions. See Image tags⁠ and Architectures⁠.

⁠Tag format

Legacy workbench-session tags bundled two R versions and two Python versions per image, for example ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10. Replacement tags pin a single R and Python version per image and follow R{r_version}-python{python_version}-{os}, for example R4.5.2-python3.14.3-ubuntu-24.04. To cover the same set of R and Python combinations, configure Workbench to use multiple session images instead of one.

⁠Quarto installation path

The legacy images installed Quarto under /opt/quarto/{version}/bin/quarto. The new workbench-session images install Quarto under /opt/quarto/bin/quarto from the Posit Apt repository. quarto and its installed tools are still symlinked to the system PATH. Update any references to the Quarto path accordingly.

⁠Session components

The legacy r-session-complete image bundled the Workbench session components directly. The workbench-session image does not. Instead, the workbench-session-init init container delivers session components into the session pod through a shared volume at runtime.

r-session-complete will not be supported by this repository. If you are still using r-session-complete, migrate to the new workbench-session images and enable the workbench-session-init init container. See the workbench-session-init README⁠ for additional details.

The legacy rstudio/workbench-session image already followed this init container pattern, so this migration step does not apply when moving from rstudio/workbench-session.

⁠What did not change

• R, Python, Jupyter, and Posit Professional Drivers installation paths under /opt
• The role of these images as session execution environments managed by the Workbench Job Launcher
• The system dependencies bundled to support popular R packages

⁠Caveats

⁠Security

Review these images before using them in production. Organizations with specific Common Vulnerabilities and Exposures (CVE) or vulnerability requirements can rebuild these images to meet their security standards.

Posit rebuilds published images weekly for Posit product editions under active support to pull in operating system patches.

⁠Image dependency licenses

These images contain third-party software (R, Python, Jupyter, Quarto, TinyTeX, Posit Professional Drivers, system libraries, and their transitive dependencies) under various licenses. You are responsible for confirming that these images and their dependencies comply with all applicable licenses.