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.

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 rstudio/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 rstudio/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 rstudio/workbench-session images
Option B) Extending one of the rstudio/workbench-session images
Option C) Building a custom rstudio/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 `rstudio/workbench-session` images

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

https://hub.docker.com/r/rstudio/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=rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10
default-container-image=rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10

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 `rstudio/workbench-session` images

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

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

Example 1: Adding R packages:

File: Dockerfile

FROM rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10

# 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 rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10

# 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 rstudio/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10

# 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:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10-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:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10-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:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10-custom
default-container-image=<DOCKER-REGISTRY>/workbench-session:ubuntu2204-r4.4.1_4.3.3-py3.12.6_3.11.10-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 `rstudio/workbench-session` 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 Dockerfiles for the rstudio/workbench-session images and their base images as a reference.

The following Dockerfiles can be used as a reference (in order of inheritance):

rstudio/product-base
- Installs and configures the following:
  - System packages
  - R versions
  - Python versions
  - Locale settings
rstudio/product-base-pro
- Inherits from rstudio/product-base
- Installs and configures the following:
  - RStudio Professional Drivers
rstudio/workbench-session
- Inherits from rstudio/product-base-pro
- Installs and configures the following:
  - System dependencies required for Posit Workbench sessions
  - Jupyterlab, Jupyter Notebooks, and Posit Workbench Jupyter extension
  - ipykernel
  - VS Code extensions
  - 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.