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)
- Add mermaid diagram illustrating JupyterHub architecture and user flow
- Move screenshots higher in document under dedicated User Interface section
- Visualize relationships between Traefik, Hub, Spawner, and user containers
- Show per-user volumes and shared storage configuration
- Improve document flow: Architecture -> UI -> Features -> Setup
- Remove tag-based trigger constraint from GitHub Actions workflow
- Workflow now triggers only on push to main, PRs, and manual dispatch
- Simplifies workflow triggers and removes version-specific pattern
- Replace 'latest' tag with explicit version 5.4.2
- Resolves hadolint DL3007 warning in CI/CD pipeline
- Ensures reproducible builds and prevents unexpected breaking changes
UI Enhancements:
- Add Font Awesome icons to all control buttons (stop, start, restart, manage volumes)
- Auto-refresh page after server stop with smooth UI transitions
- Hide/show appropriate buttons based on server state (Restart vs Manage Volumes)
- Re-inject icons removed by JupyterHub's DOM manipulation
Technical Implementation:
- MutationObserver watches for JupyterHub DOM changes after stop
- Immediate UI state correction before page refresh
- Comprehensive console logging for debugging
CI/CD:
- Add GitHub Actions workflow for Dockerfile validation with hadolint
- Triggers on push to main, version tags, and pull requests
- Uses hadolint to ensure Dockerfile best practices
Documentation enhancements:
- Add comprehensive Features section highlighting key capabilities
- Document GPU auto-detection, user self-service, isolated environments
- Include production-ready features (Traefik, TLS, Watchtower)
- Add Self-Service Volume Management subsection with visual examples
- Include three screenshots demonstrating UI features:
- Restart Server button (active state)
- Manage Volumes button (stopped state)
- Volume selection modal (checkbox interface)
- Position screenshots prominently after feature list
- Provide one-sentence descriptions for each screenshot
Technical updates:
- Increase Stop Server refresh delay to 3 seconds for stability
- Update version to 3.0.14
Screenshots stored in .resources/ directory for future reference
- Add console.log statements to track button clicks and API calls
- Log username, base URL, and button existence on page load
- Log success/error responses from API calls
- Help diagnose why restart server button does nothing
- Add stop target to gracefully stop and remove containers
- Respects compose_override.yml if present
- Stops containers without removing images or volumes
- Add custom API handlers for volume reset and server restart
- Create custom home.html template with self-service buttons and modals
- Register handlers in jupyterhub_config.py with @admin_or_self permissions
- Update Dockerfile to copy templates and handlers
- Add custom templates path to JupyterHub configuration
- Update .claude/CLAUDE.md with feature documentation
- Reset Home Volume: DELETE /hub/api/users/{username}/reset-home-volume
- Restart Server: POST /hub/api/users/{username}/restart-server
- Both features use Docker API directly via /var/run/docker.sock
- Add .claude/CLAUDE.md with comprehensive architecture documentation
- Add .claude/JOURNAL.md for tracking substantive work
- Add FEATURE_PLAN.md for Reset Home Volume and Restart Server features
- Add project.env with version tracking (1.0.0_jh-4.x)
- Update Makefile with increment_version and tag targets
- Implement auto-versioning on build and dual-tag push workflow
