Using Docker images with Posit Workbench, Launcher, and Kubernetes

Overview

The Docker images described here are intended to be used with Posit Workbench, Launcher, and Kubernetes to run sessions and jobs with R as well as Jupyter Notebooks and VS Code with Python on a Kubernetes cluster.

Docker images 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.

Layers to consider when using Docker images with Posit Workbench, Launcher, and Kubernetes

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 with Posit Workbench and Launcher, and some of the layers are optional and customizable:

• Required layers
  • Base OS or image
  • Posit Workbench session components
  • Required system packages
  • A version of R
• Optional layers
  • R packages
  • A version of Python
  • Jupyter Notebooks and JupyterLab
  • VS Code
  • Python packages
  • Posit 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.

Options for using Docker images with Posit Workbench, Launcher, and Kubernetes

There are three options for using Docker images for with Posit Workbench, Launcher, and Kubernetes for R sessions and jobs:

• Option A) Using the r-session-complete Docker image

• Option B) Extending the r-session-complete Docker image

• Option C) Building a custom r-session-complete Docker 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 install 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 the r-session-complete Docker images

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

Pre-built r-session-complete images are available from the rstudio/r-session-complete repository on Docker Hub:

https://hub.docker.com/r/rstudio/r-session-complete

The version of the Docker images that correspond to the latest stable release of Posit Workbench 2024.09 are (you will want to use the version corresponding to the version of Posit Workbench you're running):

• rstudio/r-session-complete:jammy-2025.05.1

You can refer to these Docker images in the container-images and default-container-image settings in the Launcher profiles configuration file (default /etc/rstudio/launcher.kubernetes.profiles.conf). For example:

# /etc/rstudio/launcher.kubernetes.profiles.conf

[*]
default-cpus=1
default-mem-mb=512
max-cpus=2
max-mem-mb=1024
container-images=rstudio/r-session-complete:jammy-2025.05.1
default-container-image=rstudio/r-session-complete:jammy-2025.05.1
allow-unknown-images=0

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
• Posit Workbench session components
• One version of R
• One version of Python
• Jupyter Notebooks and JupyterLab
• VS Code
• Posit Professional Drivers

Option B) Extending the r-session-complete Docker image

You can extend the r-session-complete Docker images by adding additional R, Python packages, or system packages.

Create a Dockerfile that inherits the r-session-complete image and adds R, Python, and/or system packages.

Example 1: Adding R packages to the r-session-complete image:

FROM rstudio/r-session-complete:jammy-2025.05.1

# 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 to the r-session-complete image:

FROM rstudio/r-session-complete:jammy-2025.05.1

# 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 to the r-session-complete image:

FROM rstudio/r-session-complete:jammy-2025.05.1

# 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 r-session-complete image, you can run the following command to build a custom Docker image with your additions:

docker build . -t <DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1-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 the Kubernetes cluster.

docker push <DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1-custom

Update the Launcher profiles configuration file to point to the custom Docker image (default /etc/rstudio/launcher.kubernetes.profiles.conf):

container-images=<DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1-custom
default-container-image=<DOCKER-REGISTRY>/jammy-2025.01.0-custom

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

Option C) Building a custom r-session-complete Docker image

If you need to build custom Docker images yourself (for example, to use a different base OS or include custom packages), you can use the Dockerfile for the r-session-complete Docker image as a starting point.

First, copy the Dockerfile from the rstudio/r-session-complete repository on GitHub:

• Dockerfile based on Ubuntu 22.04 (for Posit Workbench 2025.05.1)

Edit the Dockerfile as needed, and note that the resulting Dockerfile must include the following contents to work with Launcher:

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

Run the following command to build a custom Docker image based on your custom Dockerfile:

docker build . -t <DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1-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 the Kubernetes cluster.

docker push <DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1-custom

Update the Launcher profiles configuration file to point to the custom Docker image (default /etc/rstudio/launcher.kubernetes.profiles.conf):

container-images=<DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1-custom
default-container-image=<DOCKER-REGISTRY>/jammy-2025.05.1-custom

Using Docker images in an offline environment

If you are using Posit Workbench and Launcher 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 rstudio/r-session-complete:jammy-2025.05.1
docker save r-session-complete.tar

Move the tar file to the offline environment, then run the following commands:

docker load r-session-complete.tar
docker tag rstudio/r-session-complete:jammy-2024.05.1 <DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1
docker push <DOCKER-REGISTRY>/r-session-complete:jammy-2025.05.1+513.pro3

where <DOCKER-REGISTRY> is the name or URL of your Docker registry.

All Versions of the r-session-complete Docker Images

You can view a full list of r-session-complete images on the rstudio/r-session-complete repository on Docker Hub:

https://hub.docker.com/r/rstudio/r-session-complete