Added --no-startup flag to Watchtower command in compose.yml.
Previously, Watchtower would check for image updates on every container
startup/restart. Now only runs at scheduled time (midnight daily).
Removed obsolete 01_nvidia-smi.sh (GPU detection handled in jupyterhub_config.py).
Renamed 02_ensure_groups.py to 01_ensure_groups.py for sequential ordering.
Changed from containrrr/watchtower:latest to nickfedor/watchtower:latest.
New image is actively maintained and compatible with latest Docker versions.
Version bump: 3.2.11 -> 3.3.1
Added Volume Architecture diagram showing four persistent volumes per user with Docker host to container mount mapping. Diagram illustrates jupyterlab-{username}_* naming pattern for user-specific volumes (home, workspace, cache) and shared jupyterhub_shared volume. Shows mount points and example contents for each volume type, with note about CIFS mount capability for NAS integration.
Added three mermaid diagrams to README documenting system architecture and workflows. Configuration Flow diagram shows how environment variables from compose.yml flow through jupyterhub_config.py to spawned user containers, including DOCKER_SPAWNER_VOLUMES, VOLUME_DESCRIPTIONS, BUILTIN_GROUPS, pre_spawn_hook, extra_handlers, and template_paths. GPU Auto-Detection diagram illustrates the auto-detect mechanism with temporary CUDA container spawning nvidia-smi for detection. User Self-Service Workflow diagram demonstrates home page state management for restart server and manage volumes features. Converted HTML alert divs to GitHub-style WARNING blocks for better rendering.
Added journal entry #13 documenting release v3.2.11 preparation:
- Git tag creation with annotations
- RELEASE.md delta notes
- Documentation simplification (docker-socket-permissions.md from 66 to 19 lines)
- project.env update with release metadata
- Security warning corrections (host system -> Docker host)
- HTML alert styling for warnings
Updated README.md to explicitly name 'docker-privileged' group in opening
description of privileged access section for clarity.
Updated version metadata:
- VERSION_COMMENT reflects key features of v3.2.11
- Added RELEASE_TAG: RELEASE_3.2.11
- Added RELEASE_DATE: 2025-11-09
This marks the official release of version 3.2.11 with configuration-agnostic
volume management, notification broadcast, and privileged access control.
Delta release notes covering changes from v3.0.14 to v3.2.11:
- Configuration-agnostic volume management with optional descriptions
- Admin notification broadcast system
- Privileged user docker.sock access control
- Documentation following modus primaris style
- Technical improvements and upgrade notes
Following modus primaris: concise, factual, organized sections.
Added entry #12 documenting volume management refactoring to be fully
configuration-agnostic with optional descriptions, import error fixes for
jupyterhub_config.py, and README/documentation simplification following
modus primaris style.
Fixed NameError when custom_handlers.py imports from jupyterhub_config.py
by protecting all c.* assignments with 'if c is not None:' checks.
Changes:
- Wrapped c = get_config() in try-except to handle module import context
- Defined DOCKER_SPAWNER_VOLUMES as module-level constant
- Modified get_user_volume_suffixes() to accept volumes dict parameter
- USER_VOLUME_SUFFIXES calculated from constant (importable without c defined)
- Protected all c.* configuration assignments with 'if c is not None:' guards
This allows custom_handlers.py to import USER_VOLUME_SUFFIXES without
triggering "NameError: name 'get_config' is not defined" when the config
file is imported as a module rather than loaded by JupyterHub.
Volume management now works correctly - configuration can be safely imported
by handlers to validate volume names against USER_VOLUME_SUFFIXES.
Updated volume management to dynamically read volume names from
DockerSpawner.volumes configuration instead of hardcoding them:
- Added get_user_volume_suffixes() function to extract volume suffixes from
config matching jupyterlab-{username}_<suffix> pattern
- Exposed USER_VOLUME_SUFFIXES via c.JupyterHub.template_vars for templates
- Updated home.html to use Jinja2 loop generating checkboxes dynamically
from user_volume_suffixes variable
- Modified ManageVolumesHandler to validate against configured volumes
instead of hardcoded {'home', 'workspace', 'cache'}
- Removed volume descriptions (e.g., "Contains: User home directory...") to
keep UI truly agnostic
Now works correctly if volumes are renamed, added, or removed in configuration
without requiring template or handler changes. Volume names displayed exactly
as defined in config (home, workspace, cache by default).
Restructured README.md following modus primaris approach:
1. Simplified intro (one concise paragraph)
2. Features as bullet points at top
3. User Interface screenshots (with explanations before images)
4. Architecture diagram and explanation
5. Remaining sections (References, Requirements, Quickstart, etc.)
Removed duplicate Features and User Interface sections that were previously
positioned after Architecture. Content now flows logically from high-level
features to visual examples to technical architecture details.
Reordered User Interface section:
- Home control panel (server restart and volume management)
- Volume management screenshots grouped together
- Admin notification broadcast (last)
Changed format: explanation text with heading before each screenshot image,
replacing italic captions below images for better readability.
Updated entry #11 to accurately reflect the super-minimal modus primaris style
approach with line counts for each documentation file (35, 55, 66 lines) and
emphasis on "glimpse of implementation" rather than comprehensive coverage.
Added entry #11 documenting comprehensive documentation creation for
notification system, UI customization, and Docker socket permissions. Also
documented screenshot updates in README.md replacing restart server image with
complete control panel view and adding admin notification broadcast interface.
Added three new documentation files following modus primaris style:
- doc/ui-template-customization.md: Guide for extending JupyterHub UI
templates with RequireJS, Bootstrap 5, CSRF protection, and custom handlers
- doc/docker-socket-permissions.md: Docker socket access control documentation
covering group-based permissions, security implications, and best practices
- doc/notifications.md: Complete notification broadcast system documentation
including implementation details, API integration, error handling, and
troubleshooting
Updated UI screenshots in README.md:
- Replaced screenshot-restart-server.png with screenshot-home.png showing
complete user control panel (restart server + volume management)
- Added screenshot-send-notification.png showing admin notification broadcast
interface with message composer, type selector, and delivery results
All documentation follows consistent structure: brief overview, key facts in
bullet points, explanatory narrative, and technical specifications without
excessive nesting or marketing language.
Updated notification broadcast system documentation in .claude/CLAUDE.md to
reflect actual implementation details:
- Corrected message character limit from 500 to 140 characters
- Updated notification type list to include all 6 types (default, info, success,
warning, error, in-progress) instead of just 4
- Clarified authentication mechanism: temporary token generation with 5-minute
expiry via user.new_api_token() rather than retrieving existing tokens
- Fixed endpoint URL pattern showing correct base_url interpolation
- Corrected extension endpoint path (hyphen not underscore)
- Added Dismiss button feature to UI features list
- Updated error handling to include HTTP 500 and logging details
- Added explanation of one-line logging per server delivery
These changes ensure the embedded configuration accurately documents the
notification broadcast feature as implemented in version 3.2.0.
Implemented comprehensive notification broadcast functionality allowing
administrators to send notifications to all active user JupyterLab servers
simultaneously through a dedicated admin panel.
Core Features:
- Admin-only notification panel accessible at /hub/notifications
- Concurrent delivery to all active servers using asyncio with 5s timeout
- Temporary API token generation (5-minute expiry) for authentication
- Support for 6 notification types: default, info, success, warning, error, in-progress
- 140-character message limit with live character counter
- Auto-close toggle and dismiss button in notifications
- Dynamic endpoint URL construction using spawner.server.base_url
- Comprehensive error handling with user-friendly messages
- One-line logging per server with message preview and outcome
Technical Implementation:
- Created BroadcastNotificationHandler in custom_handlers.py
- Created NotificationsPageHandler for admin UI rendering
- Added notifications.html template with Bootstrap 5 form
- Registered handlers in jupyterhub_config.py extra_handlers
- Sends to /jupyterlab-notifications-extension/ingest endpoint
- Payload includes type, message, autoClose, and actions array
- Navigation link added to home.html for admin access
Integration:
- Requires jupyterlab_notifications_extension installed on JupyterLab servers
- Uses correct payload format (type field, not variant)
- Includes Dismiss action button for manual notification closure
Documentation:
- Updated .claude/CLAUDE.md with complete feature documentation
- Updated README.md Features section with notification broadcast details
- Updated .claude/JOURNAL.md with implementation summary
- Removed obsolete FEATURE_PLAN.md
Version: 3.2.0 (bumped from 3.1.2)
Implemented built-in protected group system enabling admins to grant trusted users read-write Docker socket access within their JupyterLab containers. Groups are managed through admin panel and cannot be permanently deleted.
- Add pull_policy: build to jupyterhub service
- Forces Docker Compose to use locally built image
- Prevents unnecessary pulls from Docker Hub after building
Now 'docker compose up' will use the local image built with 'make build'
- Change Docker build context from services/jupyterhub to project root
- Copy config/jupyterhub_config.py into image at /srv/jupyterhub/jupyterhub_config.py
- Users can still override with volume mount if needed
- Update all COPY paths in Dockerfile to reflect new build context
- Enables container to work out-of-the-box without external config file
Benefits:
- Image is self-contained and ready to run without dependencies
- Volume mount remains optional for custom configurations
- Default config includes GPU auto-detection and self-service features
- Add /srv/jupyterhub to sys.path before importing custom_handlers
- Separate shell scripts and Python files in Dockerfile COPY commands
- Resolves ModuleNotFoundError for custom_handlers module
- JupyterHub now starts successfully with custom API handlers
- Remove fill colors from mermaid diagram nodes
- Keep stroke colors and widths for visual distinction
- Improves compatibility with different GitHub themes (light/dark mode)
