Using Docker images with RStudio Workbench / RStudio Server Pro, Launcher, and Kubernetes

Avatar
Kristopher Overholt
Follow
Launcher is a feature of RStudio Workbench (previously RStudio Server Pro) that is only available under named user licensing. RStudio Server Pro without Launcher is available under existing server-based licensing. For questions about using Launcher with RStudio Workbench, please contact sales@rstudio.com.

Overview

The Docker images described here are intended to be used with RStudio Workbench (previously RStudio Server Pro), 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 RStudio Workbench and Launcher.

 

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

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

Some of the layers are required for the image to function with RStudio Workbench and Launcher, and some of the layers are optional and customizable:

  • Required layers
    • Base OS or image
    • RStudio 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
    • RStudio Professional Drivers
    • Other customizations

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

 

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

There are three options for using Docker images for with RStudio 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 RStudio 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 RStudio Workbench and Launcher.

After you verify the initial RStudio 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 RStudio.

 

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 RStudio 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 RStudio Workbench 2024.04 are (you will want to use the version corresponding to the version of RStudio Workbench you're running):

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

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-2024.04.0
default-container-image=rstudio/r-session-complete:jammy-2024.04.0
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
  • RStudio Workbench session components
  • One version of R
  • One version of Python
  • Jupyter Notebooks and JupyterLab
  • VS Code
  • RStudio 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-2024.04.0

# 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-2024.04.0

# 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-2024.04.0

# 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-2024.04.0-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-2024.04.0-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-2024.04.0-custom
default-container-image=<DOCKER-REGISTRY>/jammy-2024.04.0-custom

Note that you can specify multiple container-images that can be selected by RStudio 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:

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
  • RStudio 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-2024.04.0-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-2024.04.0-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-2024.04.0-custom
default-container-image=<DOCKER-REGISTRY>/jammy-2024.04.0-custom

 

Using Docker images in an offline environment

If you are using RStudio 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-2024.04.0
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.04.0 <DOCKER-REGISTRY>/r-session-complete:jammy-2024.04.0
docker push <DOCKER-REGISTRY>/r-session-complete:jammy-2024.04.0-735.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

Comments