# JupyterHub ML Environment

> JupyterHub with GPU support for ML.

- Category: AI & Machine Learning
- Difficulty: intermediate
- Components: jupyterhub, postgres, nginx
- Tags: jupyter, ml, data-science, notebooks
- Source: https://docker.recipes/ai-ml/jupyter-ml-stack

## Overview

JupyterHub is a multi-user server that spawns, manages, and proxies multiple instances of the single-user Jupyter notebook server. Originally developed to serve computational environments for hundreds of users in educational and research settings, JupyterHub enables organizations to provide centralized access to Jupyter notebooks while maintaining user isolation and resource management. It supports various authentication methods and can spawn user environments in Docker containers, making it ideal for data science teams and ML workflows.

This deployment creates a complete JupyterHub infrastructure with three core services: the main JupyterHub server for user management and notebook spawning, a PostgreSQL database (jupyterhub-db) for persistent storage of user data and hub state, and an NGINX reverse proxy for load balancing and SSL termination. The configuration includes Docker socket mounting to enable JupyterHub's DockerSpawner functionality, allowing it to create isolated containers for each user session with potential GPU access for machine learning workloads.

This stack is perfect for data science teams, educational institutions, and research organizations that need to provide multiple users with consistent, isolated Jupyter environments. The combination of JupyterHub's multi-user capabilities, PostgreSQL's robust data persistence, and NGINX's high-performance proxying creates a production-ready platform for collaborative data science and machine learning development with the flexibility to scale from small teams to hundreds of concurrent users.

## Features

- Multi-user Jupyter notebook server with user isolation and resource management
- DockerSpawner integration for containerized user environments with GPU support capability
- PostgreSQL backend for persistent storage of user data, hub state, and session management
- NGINX reverse proxy with load balancing and SSL termination support
- Configurable authentication backends including OAuth, LDAP, PAM, and custom authenticators
- Admin interface for user management, server control, and resource monitoring
- Customizable user environments through Docker images with pre-installed ML libraries
- Volume mounting support for shared datasets and collaborative workspaces

## Use cases

- Data science teams requiring shared computational environments with version-controlled notebooks
- Educational institutions providing students with consistent Python/R environments for coursework
- Research organizations needing multi-user access to GPU resources for deep learning experiments
- Corporate ML teams sharing datasets and models across different projects and users
- Training workshops and bootcamps requiring instant notebook access for participants
- Remote development teams needing centralized Jupyter environments with persistent storage
- Organizations migrating from individual Jupyter installations to centralized management

## Prerequisites

- Docker Engine with minimum 4GB RAM allocated for user containers and ML workloads
- Port 8000 available for JupyterHub web interface and port 80 for NGINX proxy
- Custom jupyterhub_config.py file configured with desired authentication and spawner settings
- NGINX configuration file (nginx.conf) with proper upstream and SSL settings
- Environment variables set for DB_PASSWORD and optional JUPYTER_PORT/NGINX_PORT customization
- Understanding of Docker container management and JupyterHub administration concepts

## docker-compose.yml

```yaml
services:
  jupyterhub:
    image: jupyterhub/jupyterhub:latest
    container_name: jupyterhub
    restart: unless-stopped
    ports:
      - "${JUPYTER_PORT:-8000}:8000"
    environment:
      - POSTGRES_HOST=jupyterhub-db
      - POSTGRES_DB=jupyterhub
      - POSTGRES_USER=jupyterhub
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - jupyterhub_data:/srv/jupyterhub
      - /var/run/docker.sock:/var/run/docker.sock
      - ./jupyterhub_config.py:/srv/jupyterhub/jupyterhub_config.py:ro
    depends_on:
      - jupyterhub-db

  jupyterhub-db:
    image: postgres:15-alpine
    container_name: jupyterhub-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=jupyterhub
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=jupyterhub
    volumes:
      - jupyter_db_data:/var/lib/postgresql/data

  nginx:
    image: nginx:alpine
    container_name: jupyter-nginx
    restart: unless-stopped
    ports:
      - "${NGINX_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

volumes:
  jupyterhub_data:
  jupyter_db_data:
```

## .env

```bash
# JupyterHub
JUPYTER_PORT=8000
DB_PASSWORD=jupyterhub_password
NGINX_PORT=80
```

## Usage notes

- Docs: https://jupyterhub.readthedocs.io/
- JupyterHub at http://localhost:8000 - multi-user notebook server
- Configure jupyterhub_config.py for authentication (OAuth, LDAP, PAM)
- Use DockerSpawner for isolated user containers with GPU support
- Mount shared datasets at /srv/data or use NFS for collaboration
- Pre-install libraries in custom Docker images for users

## Troubleshooting

- JupyterHub fails to start with 'database connection failed': Verify jupyterhub-db container is running and DB_PASSWORD environment variable matches between services
- Users cannot spawn notebooks with 'spawn failed' error: Check that Docker socket is properly mounted and JupyterHub has permissions to create containers
- NGINX returns 502 Bad Gateway: Ensure JupyterHub container is healthy and accessible on port 8000, verify nginx.conf upstream configuration
- PostgreSQL data loss after container restart: Confirm jupyter_db_data volume is properly mounted and persistent
- Out of memory errors during notebook execution: Increase Docker memory limits and configure resource limits in jupyterhub_config.py
- Authentication loops or login failures: Review jupyterhub_config.py authentication settings and ensure proper authenticator configuration

