mirror of https://github.com/stellarshenson/stellars-jupyterhub-ds.git synced 2026-03-08 06:00:29 +00:00

Files

stellarshenson 7ba01412d1 docs: simplify documentation to minimal modus primaris style

Drastically reduced documentation length focusing only on essential
implementation facts:

- doc/notifications.md: Reduced from 250 to 35 lines - key technical facts,
  handler implementation, template details, dependencies, error handling
- doc/ui-template-customization.md: Reduced from 132 to 55 lines - technical
  facts, JavaScript patterns, Bootstrap 5 syntax, CSRF protection, build process
- doc/docker-socket-permissions.md: Reduced from 186 to 66 lines - implementation
  facts, pre-spawn hook code, built-in group system, security implications, usage

All documentation now follows super-minimal "glimpse of implementation" approach
with bullet points and code snippets, absent of lengthy narrative and marketing
language.

2025-11-09 22:23:54 +01:00

2.1 KiB

Raw Blame History

Docker Socket Access Control

Group-based Docker socket access for user containers enabling container orchestration from within JupyterLab. Controlled via docker-privileged built-in group.

Key Implementation Facts:

JupyterHub container mounts /var/run/docker.sock:rw for DockerSpawner (required)
User containers conditionally receive socket based on group membership
Pre-spawn hook checks user.groups before mounting socket
Group membership changes require server restart to take effect
Built-in group protected from deletion (auto-recreates)

Pre-Spawn Hook (config/jupyterhub_config.py):

async def pre_spawn_hook(spawner):
    user = spawner.user

    # Check if user is in docker-privileged group
    if any(group.name == 'docker-privileged' for group in user.groups):
        spawner.extra_host_config = {
            'binds': {
                '/var/run/docker.sock': {
                    'bind': '/var/run/docker.sock',
                    'mode': 'rw'
                }
            }
        }

Built-in Group System:

Single source of truth: BUILTIN_GROUPS = ['docker-privileged'] in jupyterhub_config.py
Startup script 02_ensure_groups.py reads config and creates missing groups
Pre-spawn hook recreates group if deleted during runtime
Cannot be permanently removed

Managing Access (via admin panel at /hub/admin):

Navigate to Groups section
Click docker-privileged group
Add/remove usernames
User must restart server for changes to apply

Security Implications: Docker socket provides root-equivalent host access:

Create privileged containers
Mount any host directory
Access other users' containers/volumes
Read sensitive host files
Escape container isolation

Only grant access to fully trusted users who already have legitimate root/sudo equivalency.

Use Cases:

Building Docker images within JupyterLab
Running development services (databases, APIs)
Container orchestration development
Infrastructure as Code testing
Teaching Docker concepts

Auditing:

# View Docker daemon logs
sudo journalctl -u docker.service -f

# Monitor Docker events
docker events

2.1 KiB Raw Blame History

Docker Socket Access Control

2.1 KiB

Raw Blame History