Skip to content

Latest commit

 

History

History
389 lines (299 loc) · 14.9 KB

README.md

File metadata and controls

389 lines (299 loc) · 14.9 KB
Raw

minimal-readme compliant Project Status: Active – The project has reached a stable, usable state and is being actively developed. Donate using Liberapay

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.
👉 The current state may eventually be backported to versions ≥ 4.0.4.

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

Screenshot

Build chain

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

Features

  • JupyterLab: A web-based interactive development environment for Jupyter notebooks, code, and data. The images include
    • code-server: Code - OSS in the browser.
    • Git: A distributed version-control system for tracking changes in source code.
    • Git LFS: A Git extension for versioning large files.
    • GRASS GIS: A free and open source Geographic Information System (GIS).
      ℹ️ qgisprocess image
    • Neovim: Vim-fork focused on extensibility and usability. (4.4.1+)
    • Orfeo Toolbox: An open-source project for state-of-the-art remote sensing.
      ℹ️ qgisprocess image (amd64 only)
    • Pandoc: A universal markup converter.
    • Python: An interpreted, object-oriented, high-level programming language with dynamic semantics.
    • QGIS: A free, open source, cross platform (lin/win/mac) geographical information system (GIS).
      ℹ️ qgisprocess image
    • Quarto: A scientific and technical publishing system built on Pandoc.
      ℹ️ verse+ images
    • R: A language and environment for statistical computing and graphics.
    • radian: An alternative console for R with multiline editing and rich syntax highlight.
    • RStudio: An integrated development environment (IDE) for R. (4.4.0+)
    • SAGA GIS: A Geographic Information System (GIS) software with immense capabilities for geodata processing and analysis.
      ℹ️ qgisprocess image
    • TinyTeX: A lightweight, cross-platform, portable, and easy-to-maintain LaTeX distribution based on TeX Live.
      ℹ️ verse+ images
    • Zsh: A shell designed for interactive use, although it is also a powerful scripting language.

👉 See the Version Matrix for detailed information.

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

Subtags

  • {R_VERSION,latest}-root (versions ≥ 4.2.0): Container runs as root
  • {R_VERSION,latest}-devtools (versions ≥ 4.2.2): Includes the requirements according to
  • {R_VERSION,latest}-devtools-root: The combination of both
  • {R_VERSION,latest}-docker (versions ≥ 4.2.2): Includes
    • docker-ce-cli
    • docker-buildx-plugin
    • docker-compose-plugin
    • docker-scan-plugin (amd64 only)
  • {R_VERSION,latest}-docker-root: The combination of both
  • {R_VERSION,latest}-devtools-docker: The combination of both
  • {R_VERSION,latest}-devtools-docker-root: The combination of all three

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.
❗ 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}.
ℹ️ 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

❗ 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):

Extension Environment variable
GitHub Pull Requests and Issues GITHUB_TOKEN: Personal access token with scopes repo and user.1
GitLab Workflow GITLAB_WORKFLOW_INSTANCE_URL: GitLab instance URL (e.g. https://gitlab.com).
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
    👉 Since R 4.0.4 (2021-02-15)
    ℹ️ Runs on Apple M series using Docker Desktop.
  2. Base image: Debian instead of Ubuntu
    ℹ️ CUDA-based images use Ubuntu.
  3. IDE: code-server next to RStudio
    ℹ️ 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.

  • Integration of self-signed CA certificates to enable communication with web services on the intranet.
  • Setting up the necessary environment variables so that everything works behind a corporate proxy server.

Additionally, the JupyterHub setup can be customised to allow

  • authentication with AD/LDAP
  • mounting CIFS/SMB file shares

and much more.

Sponsors

Work partially funded by

Agroscope

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 [email protected].

Footnotes

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