Using Docker Images

Workbench | Advanced

Docker images for Workbench sessions can include a version of R, Python, and common R/Python packages that are already installed, which allows users to work within R sessions and jobs and Python with Jupyter Notebooks and VS Code without having to install and compile packages for each user.

The sections below provide different options for using, customizing, and building Docker images for Posit Workbench and Launcher.

NoteContainer image transition

Posit Workbench container images are published under the posit/* organization on Docker Hub. The images are also available as ghcr.io/posit-dev/* on the GitHub Container Registry. The legacy rstudio/* images continue to be built during the transition to these new repositories.

If you deploy with the Workbench Helm chart, version 0.20.0 and later default to the new image repositories. Version 0.20.0 includes breaking changes that affect existing chart values, such as the removal of image.tagPrefix and a new default OS. See the Helm chart Migrating to Posit Images guide for the complete list of changes and migration steps.

Docker layers to consider

There are multiple layers to consider when building and using Docker images with Posit Workbench, Launcher, and Kubernetes.

Some of the layers are required for the image to function and some of the layers are optional and customizable:

Required layers

  • Base OS or image
  • Required system packages
  • A version of R

Optional layers

  • R packages
  • A version of Python
  • Jupyter Notebooks and JupyterLab
  • VS Code
  • Python packages
  • RStudio Professional Drivers
  • Other customizations

You can use one or more Docker images in Posit Workbench and Launcher with different versions of R and Python as well as different sets of packages. You can also enable an option for Posit Workbench users to be able to specify arbitrary Docker images for their R sessions and jobs.

Session init container

Workbench sessions also require Workbench session components to function. The provided posit/workbench-session images do not include the Workbench session components by default. In Kubernetes based Launcher clusters, we recommend using Workbench’s session init container to ensure that the Workbench session components are available in the session container. This feature can be enabled by adding the following to your Workbench configuration file:

File: /etc/rstudio/rserver.conf
launcher-sessions-auto-update=1

When this setting is configured, Workbench will automatically configure sessions to use the posit/workbench-session-init image as an init container. This image includes the Workbench session components and will copy the components into the session container during Pod initialization. See the Workbench session init container section for more information.

Options for using Docker images

There are three options for using Docker images:

  • Option A) Using one of the default posit/workbench-session images
  • Option B) Extending one of the posit/workbench-session images
  • Option C) Building a custom posit/workbench-session image

We test and verify the functionality of Posit Workbench, Launcher, and Kubernetes using pre-built Docker images provided in Option A.

We recommend starting with the pre-built images during the installation, setup, configuration, and testing of Posit Workbench and Launcher.

After you verify the initial Posit Workbench and Launcher functionality, you can then choose to extend the pre-built images or build custom images to fit your needs using Options B and C. Note that custom Docker images are not supported by Posit.

Option A) Using one of the default posit/workbench-session images

Pre-built workbench-session images are available from the posit/workbench-session repository on Docker Hub:

https://hub.docker.com/r/posit/workbench-session

You can refer to these Docker images in the container-images and default-container-image settings in the Launcher profiles configuration file.

File:/etc/rstudio/launcher.kubernetes.profiles.conf
container-images=posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04
default-container-image=posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04

You will need to ensure that the Kubernetes worker nodes have the ability to pull images from the online Docker Hub registry, or refer to the steps in the “Using Docker images in an offline environment” section below to download and use the images in an offline environment.

These images include the following layers:

  • Base OS: Ubuntu 22.04
  • Required system packages
  • Two versions of R
  • Two versions of Python
  • Jupyter Notebooks and JupyterLab
  • RStudio Professional Drivers

Option B) Extending one of the posit/workbench-session images

You can extend the posit/workbench-session images by adding additional R, Python packages, or system packages.

Create a Dockerfile that inherits one of the posit/workbench-session images and adds R, Python packages, and/or system packages.

Example 1: Adding R packages:

File: Dockerfile
FROM posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04

# Install additional R packages

RUN /opt/R/${R_VERSION}/bin/R -e 'install.packages("gt", repos="https://packagemanager.rstudio.com/cran/__linux__/jammy/latest")' && \
    /opt/R/${R_VERSION}/bin/R -e 'install.packages("dbplyr", repos="https://packagemanager.posit.co/cran/__linux__/jammy/latest")' && \
    /opt/R/${R_VERSION}/bin/R -e 'install.packages("shinydashboard", repos="https://packagemanager.rstudio.com/cran/__linux__/jammy/latest")'

Example 2: Adding Python packages:

File: Dockerfile
FROM posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04

# Install additional Python packages

RUN /opt/python/${PYTHON_VERSION}/bin/pip install pytorch && \
    /opt/python/${PYTHON_VERSION}/bin/pip install eli5 && \
    /opt/python/${PYTHON_VERSION}/bin/pip install sympy

Example 3: Adding system packages:

File: Dockerfile
FROM posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04

# Install additional system packages

RUN apt-get update && \
    apt-get install -y \
    package1 \
    package2 && \
    rm -rf /var/lib/apt/lists/*

Once you’ve made additions to the Dockerfile, you can run the following command to build a custom Docker image:

docker build . -t <DOCKER-REGISTRY>/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04-custom

Where <DOCKER_REGISTRY> is the name or URL of your Docker registry.

Push the image to a Docker registry that is accessible from the worker nodes in your Kubernetes cluster:

docker push <DOCKER-REGISTRY>/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04-custom

Update the Launcher profiles configuration file to point to the custom Docker image:

File:/etc/rstudio/launcher.kubernetes.profiles.conf
container-images=<DOCKER-REGISTRY>/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04-custom
default-container-image=<DOCKER-REGISTRY>/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04-custom
Note

You can specify multiple container-images that can be selected by Posit Workbench users when starting new sessions or jobs.

Option C) Building a custom posit/workbench-session image

To build custom Docker images yourself (for a different base OS or extra packages, for example), use the published posit/workbench-session Containerfiles. All Workbench Containerfiles are available in the posit-dev/images-workbench repository.

The published workbench-session image installs and configures the following components:

  • A base Ubuntu OS with required system packages
  • R and Python versions
  • RStudio Professional Drivers
  • System dependencies required for Posit Workbench sessions
  • JupyterLab, Jupyter Notebooks, and the Posit Workbench Jupyter extension
  • ipykernel
  • VS Code and Positron extensions

Create a Dockerfile and copy the contents of the Dockerfiles above and edit as needed, and note the resulting Dockerfile must include the following contents to work with Posit Workbench:

  • Base OS
  • Required system packages
  • A version of R
  • Port 8788 must be exposed from the container

Once you’ve made changes to the Dockerfile, you can build a custom Docker image using the same steps as in Option B.

Using Docker images in an offline environment

If you are using Workbench in an environment that does not have network access to pull images from Docker Hub, you can pull the image, save it to disk, move it to the offline environment, load the image, tag the image, and push it to a Docker registry that is accessible from the worker nodes in the Kubernetes cluster.

In the environment with access to Docker Hub, run the following commands:

docker pull posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04
docker save -o workbench-session-R4.4.3-python3.12.13-ubuntu-24.04.tar posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04

Move the workbench-session-R4.4.3-python3.12.13-ubuntu-24.04.tar file to the offline environment and run the following commands:

docker load -i workbench-session-R4.4.3-python3.12.13-ubuntu-24.04.tar
docker tag posit/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04 <DOCKER-REGISTRY>/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04
docker push <DOCKER-REGISTRY>/workbench-session:R4.4.3-python3.12.13-ubuntu-24.04

Where <DOCKER_REGISTRY> is the name or URL of your Docker registry.

All versions of the posit/workbench-session images

You can view a full list of the available posit/workbench-session images on Docker Hub:

https://hub.docker.com/r/posit/workbench-session

Using images for Workbench jobs

Any image can be used for Workbench jobs. However, in order to use some advanced job features like audited jobs and interpreter inspection, some Workbench session components need to be present on the image.

Getting components onto job images

Option 1: Using init container (recommended)

The recommended approach is to use the Workbench init container, which automatically provides the necessary Workbench job components without requiring them to be baked into your image.

Enable this feature by adding the following to your Workbench configuration:

File: /etc/rstudio/rserver.conf
launcher-sessions-auto-update=1

This allows job components to be bootstrapped into any image and does not add additional requirements to the Docker images that you use with Workbench jobs.

See the Workbench session init container section for more details.

Option 2: Image inheritance

Alternatively, you can inherit your job’s image from the posit/workbench-session images you prepared for sessions above.

Python and R version consistency

We recommend matching R and Python versions between sessions and jobs. Version mismatches can cause unexpected errors and increase troubleshooting complexity.

For example, Python virtual environments are commonly stored in the user’s home directory (e.g., ~/.virtualenvs/myenv). When you create a virtual environment in a session, it creates symbolic links to the specific Python interpreter used to create it (e.g., /opt/python/3.11.13/bin/python). If you later launch a job using an image with a different Python version or installation path, the virtual environment fails to load. This happens because those symbolic links point to a Python installation that does not exist or is incompatible.

To allow the virtual environment to run correctly in both the session and the job, ensure that both the job and the session image install the same versions of Python and R in the same locations.

Back to top