13 Jupyter Sessions
13.1 Overview
RStudio Server Pro allows you to launch Jupyter sessions from the home page via the Job Launcher, if configured. Users have the option of starting either JupyterLab or Jupyter Notebook sessions that allow them to work with Jupyter while still working within the administrative framework provided by RStudio, such as authentication, PAM session management, etc.
Before Jupyter sessions can be launched, the Job Launcher must be setup correctly. For more information, see the Job Launcher section.
13.2 Configuration
13.2.1 Jupyter configuration
Configuration of the Jupyter feature is handled via the config file /etc/rstudio/jupyter.conf
. Note that this file is not automatically created by RStudio, and must be created before being configured, and the Jupyter feature is disabled by default. The following table lists the various configuration options that are available to be specified in the jupyter.conf
configuration file:
/etc/rstudio/jupyter.conf
Config Option | Description | Default Value | |
---|---|---|---|
labs-enabled | Enables launching of JupyterLab sessions. | 0 (disabled) | |
notebooks-enabled | Enabled launching of Jupyter Notebook sessions. | 0 (disabled) | |
jupyter-exe | Path to the Jupyter executable. | /usr/local/bin/jupyter | |
lab-command | The Jupyter command to run when starting a Lab session. | lab | |
lab-args | Additional arguments to be passed to the Jupyter Lab command. It is recommended that you do not change this unless you know what you’re doing! | ||
notebook-command | The Jupyter comman to run when starting a Notebook session. | notebook | |
notebook-args | Additional arguments to be passed to the Jupyter Notebook command. It is recommended that you do not change this unless you know what you’re doing! | ||
session-clusters | List of available Job Launcher clusters for launching Jupyter sessions. Leave blank to specify all clusters. | ||
default-session-cluster | The default Job Launcher cluster to use when launching a Jupyter session. | ||
default-session-container-image | The default container image to use when launching a containerized Jupyter session. | ||
session-container-images | Comma-delimited list of images that may be used for running Jupyter sessions. | ||
jupyter-session-path | Path to the Jupyter Session launcher executable/script. It is recommended that you do not change this unless you know what you’re doing, and you need to point to a different script. | /usr/lib/rstudio-server/bin/jupyter-session-run | |
session-no-profile | Enables/disables running of bash profile scripts when starting Jupyter sessions. | 0 (run profile scripts) |
For example, your jupyter.conf
file might look like the following:
/etc/rstudio/jupyter.conf
jupyter-exe=/usr/bin/jupyter
labs-enabled=1
notebooks-enabled=1
default-session-cluster=Kubernetes
default-session-container-image=rstudio:jupyter-session
13.2.2 Launcher Configuration
When creating containerized Jupyter sessions via the Job Launcher, you will need to specify mount points as appropriate to mount the users’ home drives and any other desired paths. In order for sessions to run properly within containers, it is required to mount the home directories into the containers.
For more information, see Launcher Mounts. Note that you can specify the WorkbenchType
with either JupyterLab
or Jupyter Notebook
to configure mount entries that should only be mounted for JupyterLab and Jupyter Notebook sessions, respectively.
13.2.3 Container Configuration
When running Jupyter sessions in containers, such as by using the Kubernetes Job Launcher plugin, you will need to ensure that the image(s) used to launch Jupyter sessions contain, at mininum, the following:
- Python 2.7 or Python 3.x
- JupyterLab and/or Jupyter Notebook installation
- RSP session binaries
- If creating container users (see Server Configuration), you must have the
libuser1-dev
orlibuser-devel
packages, depending on your platform to install the libuser library and development tools.
For ease of use, it is recommended that you use the r-session-complete
Docker image as a base for any Jupyter session images you intend to create. This will allow you to use that one base image to provide Jupyter itself and a default version of Python, which you can extend if necessary to add/modify Jupyter versions or add additional versions of Python if desired. See Docker Hub for more information.