Skip to content

Latest commit

 

History

History
363 lines (272 loc) · 12.7 KB

README.md

File metadata and controls

363 lines (272 loc) · 12.7 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 Julia docker stack for GPU accelerated docker images.

JupyterLab Julia docker stack

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

Images considered stable for Julia versions ≥ 1.7.3.
👉 The current state may eventually be backported to versions ≥ 1.5.4.

🔬 Check out jupyterlab/julia/pubtools at https://demo.jupyter.b-data.ch.

Screenshot

Build chain

base → pubtools

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.
    • Julia: A high-level, high-performance dynamic language for technical computing.
    • Neovim: Vim-fork focused on extensibility and usability. (1.10.5+)
    • Pandoc: A universal markup converter.
    • Python: An interpreted, object-oriented, high-level programming language with dynamic semantics.
    • Quarto: A scientific and technical publishing system built on Pandoc.
      ℹ️ pubtools image
    • TinyTeX: A lightweight, cross-platform, portable, and easy-to-maintain LaTeX distribution based on TeX Live.
      ℹ️ pubtools image
    • 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

  • {JULIA_VERSION,latest}-root (versions ≥ 1.7.3): Container runs as root
  • {JULIA_VERSION,latest}-devtools (versions ≥ 1.8.2): Includes the requirements according to
  • {JULIA_VERSION,latest}-devtools-root: The combination of both
  • {JULIA_VERSION,latest}-docker (versions ≥ 1.8.5): Includes
    • docker-ce-cli
    • docker-buildx-plugin
    • docker-compose-plugin
    • docker-scan-plugin (amd64 only)
  • {JULIA_VERSION,latest}-docker-root: The combination of both
  • {JULIA_VERSION,latest}-devtools-docker: The combination of both
  • {JULIA_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 JULIA_VERSION=1.11.2 \
  -t jupyterlab/julia/base \
  -f latest.Dockerfile .

version:

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

For MAJOR.MINOR.PATCH ≥ 1.7.3.

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 Julia version ≥ 1.10.1.

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/julia/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, 1.9.4+)

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

Pluto

To add a JupyterLab Launcher icon for Pluto:

  1. Terminal: Install Pluto

    julia -e 'Pkg.add("Pluto")'

  2. Terminal: Install jupyter-pluto-proxy

    pip install jupyter-pluto-proxy

  3. Restart the container

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 project

What makes this project different:

  1. Multi-arch: linux/amd64, linux/arm64/v8
    👉 Since Julia 1.5.4 (2021-03-11)
    ℹ️ 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 JupyterLab
    ℹ️ 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.

License

Copyright © 2020 b-data GmbH

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

Footnotes

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