Cyper JupyterHub

A NixOS-managed JupyterHub deployment for www.cyperpunk.de/jupyter/, using Kanidm for OIDC authentication and DockerSpawner for per-user notebook containers. Built for teaching and workshops.

Overview

• Auth: Kanidm OIDC via GenericOAuthenticator — no local Unix accounts, access gated by the jupyterhub_users Kanidm group.
• Spawner: DockerSpawner, one container per user, image pulled from a private registry.
• Storage: each user's notebook data lives on the host at /storage/internal/jupyter/<username>, bind-mounted into the container at /home/jovyan/work. This is a plain disk (not impermanence-managed), so files survive container restarts/rebuilds and can be copied in directly over the network share — no upload UI needed.
• Image: custom image (cyper-jupyter) based on quay.io/jupyter/datascience-notebook, themed with Catppuccin Mocha (Peach accent) and extended with a small set of JupyterLab extensions for teaching.

Repo layout

.
├── Dockerfile                # custom notebook image
├── requirements.txt           # Python/JupyterLab extension pins
├── overrides.json             # default JupyterLab theme settings, baked into the image
└── startup/
    └── 00-catppuccin.py       # IPython startup script: matplotlib + terminal theming

Theming

JupyterLab UI, code/terminal syntax highlighting, and matplotlib/seaborn plot output are all themed Catppuccin Mocha by default on first login — no user configuration needed.

• UI theme: catppuccin-jupyterlab — default set via overrides.json.
• Terminal/IPython highlighting + plot palette: catppuccin (Python package) — applied via startup/00-catppuccin.py, which runs automatically on every kernel start.

Docs: Catppuccin JupyterLab README · Catppuccin Python README

Included extensions

jupyter-resource-usage

Shows each user's own CPU and memory usage live in the JupyterLab status bar (bottom right). Useful in a shared/workshop environment so students can see if they're approaching container resource limits.

Usage: nothing to do — once installed, the usage indicator just appears in the status bar at the bottom of the JupyterLab window.

Docs: jupyterhub/jupyter-resource-usage

---

jupyterlab_image_editor

A simple in-browser image editor. Lets students crop, annotate, and touch up images without leaving JupyterLab.

Usage: right-click any image file in the file browser (or an image opened from a notebook output) → Open With → Image Editor. Basic tools (crop, draw, text, shapes) appear in a toolbar above the image.

Docs: jupyterlab-contrib/jlab-image-editor

---

jupyterlab-vim

Adds Vim keybindings to the code cell editor (not the command-mode cell selector, which already has Vim-like j/k/dd bindings by default in JupyterLab).

Usage: once installed, click into any code cell — you're in Vim's normal mode by default. Press i to enter insert mode, Esc to return to normal mode, :w is disabled (saving is handled by JupyterLab's own Ctrl+S). Toggle on/off entirely via Settings → Vim Notebook Cell, or per-keybinding in Settings → Advanced Settings Editor → Vim.

Docs: jwkvam/jupyterlab-vim

---

jupyterlab-notify

Sends a browser notification when a long-running cell finishes executing.

Usage: enable per-notebook via Settings → Notify for Cell Execution, or run a cell and switch to another browser tab/window; when it finishes, a native OS notification pops up (you'll be prompted to allow notifications for the site the first time). No special syntax needed in the notebook itself.

Note: this install only covers browser-side notifications (tab must stay open). Notifying after the browser is fully closed requires the optional jupyterlab-notify[server-side-execution] extra plus jupyter-server-nbmodel, which isn't installed here.

Docs: deshaw/jupyterlab-notify

nbgrader

Adds a Create Assignment toolbar to the notebook editor for tagging cells as autograded, manual grade, or solution. This install only covers authoring — producing notebooks with the right grading metadata baked in — not the grading workflow itself (no Formgrader UI, no course setup, no assignment release/collect through the hub).

Usage: open a notebook, click View → Create Assignment Toolbar (or the toolbar icon if already visible) to reveal per-cell controls. Select a cell, then choose its type from the dropdown that appears above it:

• Manual — student answers this manually; graded by hand later.
• Autograded answer — student-editable region; checked against test cases.
• Autograded tests — hidden test cells that run against the student's answer.
• Read-only — instructions/setup cells students can't edit.

Once cells are tagged, the notebook can be handed off to any nbgrader-based grading setup elsewhere — this image doesn't run the grading side.

Docs: nbgrader documentation · Creating and grading assignments

manim

Mathematical animation library (used by 3Blue1Brown-style videos). Lets you build and render animated math/geometry explanations directly from a notebook — useful for visual walkthroughs in workshop material.

Usage: import and use the %%manim cell magic to render a scene inline in the notebook:

from manim import *

%%manim -qm CircleExample

class CircleExample(Scene):
    def construct(self):
        circle = Circle()
        self.play(Create(circle))

-qm renders at medium quality (fast); use -qh for high quality when producing a final video. Output renders as an embedded video player in the cell output.

Requires system-level cairo, pango, ffmpeg, and a LaTeX install for formula rendering — all included in this image's Dockerfile.

Docs: Manim Community documentation

---

jupyterlab-markup

Extends JupyterLab's built-in Markdown preview with GitHub-flavored extras: tables, footnotes, definition lists, and a few other markdown-it plugins not covered by plain CommonMark.

Usage: nothing to configure — right-click any .md file → Open With → Markdown Preview (or just double-click it). Tables, footnotes, etc. now render correctly in that preview without any extra syntax.

Docs: jupyterlab-contrib/jupyterlab-markup

Infrastructure docs

• JupyterHub
• DockerSpawner
• OAuthenticator (GenericOAuthenticator)
• Kanidm