Home

Awesome

minimal-readme compliant Project Status: Active – The project has reached a stable, usable state and is being actively developed. <a href="https://liberapay.com/benz0li/donate"><img src="https://liberapay.com/assets/widgets/donate.svg" alt="Donate using Liberapay" height="20"></a>

See the CUDA-based JupyterLab R docker stack for GPU accelerated docker images.

JupyterLab R docker stack

Multi-arch (linux/amd64, linux/arm64/v8) docker images:

Images considered stable for R versions ≥ 4.2.0.
:point_right: The current state may eventually be backported to versions ≥ 4.0.4.

:microscope: Check out jupyterlab/r/verse at https://demo.jupyter.b-data.ch.

Screenshot

Build chain

base → tidyverse → verse → geospatial → qgisprocess
:information_source: The term verse+ means verse or later in the build chain.

Features

:point_right: See the Version Matrix for detailed information.

The following extensions are pre-installed for code-server:

Subtags

Table of Contents

Prerequisites

This projects requires an installation of docker.

Install

To install docker, follow the instructions for your platform:

Usage

Build image (base)

latest:

cd base && docker build \
  --build-arg R_VERSION=4.4.2 \
  -t jupyterlab/r/base \
  -f latest.Dockerfile .

version:

cd base && docker build \
  -t jupyterlab/r/base:MAJOR.MINOR.PATCH \
  -f MAJOR.MINOR.PATCH.Dockerfile .

For MAJOR.MINOR.PATCH ≥ 4.2.0.

Create home directory

Create an empty directory using docker:

docker run --rm \
  -v "${PWD}/jupyterlab-jovyan":/dummy \
  alpine chown 1000:100 /dummy

It will be bind mounted as the JupyterLab user's home directory and automatically populated.
:exclamation: Bind mounting a subfolder of the home directory is only possible for images with R version ≥ 4.3.2.

Run container

self built:

docker run -it --rm \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  -e NB_UID=$(id -u) \
  -e NB_GID=$(id -g) \
  -e CHOWN_HOME=yes \
  -e CHOWN_HOME_OPTS='-R' \
  jupyterlab/r/base[:MAJOR.MINOR.PATCH]

from the project's GitLab Container Registries:

docker run -it --rm \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  -e NB_UID=$(id -u) \
  -e NB_GID=$(id -g) \
  -e CHOWN_HOME=yes \
  -e CHOWN_HOME_OPTS='-R' \
  IMAGE[:MAJOR[.MINOR[.PATCH]]]

IMAGE being one of

The use of the -v flag in the command mounts the empty directory on the host (${PWD}/jupyterlab-jovyan in the command) as /home/jovyan in the container.

-e NB_UID=$(id -u) -e NB_GID=$(id -g) instructs the startup script to switch the user ID and the primary group ID of ${NB_USER} to the user and group ID of the one executing the command.

-e CHOWN_HOME=yes -e CHOWN_HOME_OPTS='-R' instructs the startup script to recursively change the ${NB_USER} home directory owner and group to the current value of ${NB_UID} and ${NB_GID}.
:information_source: This is only required for the first run.

The server logs appear in the terminal.

Using Podman (rootless mode, 4.3.2+)

Create an empty home directory:

mkdir "${PWD}/jupyterlab-root"

Use the following command to run the container as root:

podman run -it --rm \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-root":/home/root \
  -e NB_USER=root \
  -e NB_UID=0 \
  -e NB_GID=0 \
  -e NOTEBOOK_ARGS="--allow-root" \
  IMAGE[:MAJOR[.MINOR[.PATCH]]]

Using Docker Desktop

Creating a home directory might not be required. Also

docker run -it --rm \
  -p 8888:8888 \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  IMAGE[:MAJOR[.MINOR[.PATCH]]]

might be sufficient.

Credential storage

:exclamation: Keyring services are not available due to the difficulties of setting them up in containers.
Therefore, provide login credentials for the following extensions as environment variables (-e):

ExtensionEnvironment variable
GitHub Pull Requests and IssuesGITHUB_TOKEN: Personal access token with scopes repo and user.1
GitLab WorkflowGITLAB_WORKFLOW_INSTANCE_URL: GitLab instance URL (e.g. https://gitlab.com).<br>GITLAB_WORKFLOW_TOKEN: Personal access token with scopes api and read_user.

Misc

marimo

To add a JupyterLab Launcher icon for marimo:

  1. Terminal: Install marimo and click

    pip install marimo click

  2. Terminal: Install jupyter-marimo-proxy

    pip install git+https://github.com/b-data/jupyter-marimo-proxy.git@jupyterlab-docker-stack

  3. Restart the container

Similar projects

What makes this project different:

  1. Multi-arch: linux/amd64, linux/arm64/v8
    :point_right: Since R 4.0.4 (2021-02-15)
    :information_source: Runs on Apple M series using Docker Desktop.
  2. Base image: Debian instead of Ubuntu
    :information_source: CUDA-based images use Ubuntu.
  3. IDE: code-server next to RStudio
    :information_source: code-server = Code - OSS in the browser.
  4. Just Python – no Conda / Mamba

See Notes for tweaks, settings, etc.

Contributing

PRs accepted. Please submit to the GitLab repository.

This project follows the Contributor Covenant Code of Conduct.

Support

Community support: Open a new discussion here. Commercial support: Contact b-data by email.

b-data tailors the JupyterLab images to your needs, e.g.

Additionally, the JupyterHub setup can be customised to allow

and much more.

Sponsors

Work partially funded by

<a href="https://www.agroscope.admin.ch/agroscope/en/home.html"><img src="assets/WBF_agroscope_e_rgb_pos_quer_1024.jpg" alt="Agroscope" width="560"></a>

License

Copyright © 2020 b-data GmbH

Distributed under the terms of the MIT License, with exceptions.

Trademarks

RStudio® is a trademark of Posit Software, PBC, all rights reserved, and may be registered in the United States Patent and Trademark Office and in other countries.

The use of the trademarked term RStudio® and the distribution of the RStudio binaries through the images hosted on b-data's GitLab Container Registry (glcr.b-data.ch) has been granted by explicit permission of Posit Software, PBC. Please review Posit’s Trademark Guidelines and address inquiries about further distribution to permissions@posit.co.

Footnotes

  1. Device activation may require a one-time login from the extension's sidebar. ↩