stellars-jupyterhub-ds/compose.yml

# --------------------------------------------------------------------------------------------------
#
#   Stellars Jupyterhub DS Platform 
#   Project Home: https://github.com/stellarshenson/stellars-jupyterhub-ds
#   This compose file support both GPU and non-GPU platforms
#
#   Jupyter hub      - https://localhost/jupyterhub
#
# --------------------------------------------------------------------------------------------------

services:

  # Proxy for smart trafic routing to make it possible to host multiple similar containers 
  # exposing ports 80, 413 & 8080 to force docker to keep only one traefik service
  # traefik dashboard is available under http://localhost:8080/dashboard
  traefik:
    image: traefik:latest
    container_name: ${COMPOSE_PROJECT_NAME:-stellars-jupyterhub-ds}-traefik
    command:
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--api.dashboard=true"
      - "--api.insecure=true"  
      - "--providers.file.filename=/mnt/certs/certs.yml" # certificates generated by jupyterlab container
      - "--serverstransport.insecureskipverify=true" # required for https passthrough
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # docker socket to use services labels
      - jupyterhub_certs:/mnt/certs # certificates (generated in jupyterhub image)
    depends_on:
      jupyterhub:
        condition: service_healthy
    networks:
      - jupyterhub_network
    restart: unless-stopped

  # service for management of a series of users and their jupyterlab
  # environments. it is internally managed via a proxy that redirects 
  # users to their dedicated environments
  jupyterhub:
    build:
      context: .
      dockerfile: services/jupyterhub/Dockerfile.jupyterhub
      args:
        - VERSION=${VERSION:-dev}
    image: stellars/stellars-jupyterhub-ds:latest
    pull_policy: build
    container_name: ${COMPOSE_PROJECT_NAME:-stellars-jupyterhub-ds}-jupyterhub
    volumes:
      - ./config/jupyterhub_config.py:/srv/jupyterhub/jupyterhub_config.py:ro # config file (read only)
      - jupyterhub_certs:/mnt/certs # certificates (generated in jupyterhub image)
      - /var/run/docker.sock:/var/run/docker.sock:rw # docker socket to use spawner
      - jupyterhub_data:/data # database and cookie secrets
      - jupyterhub_shared:/mnt/shared # shared volume across environments
      - /var/run/docker.sock:/var/run/docker.sock:ro # for nvidia autodetection
    environment:
      # Core settings
      - JUPYTERHUB_ADMIN=admin # this username will be a JupyterHub admin
      - JUPYTERHUB_BASE_URL=/jupyterhub # default URL prefix
      - JUPYTERHUB_SIGNUP_ENABLED=1 # user self-registration: 0=disabled, 1=enabled
      - JUPYTERHUB_SSL_ENABLED=0 # direct SSL: 0=disabled (use Traefik), 1=enabled
      - JUPYTERHUB_AUTOGENERATED_PASSWORD_WORDS=4 # words in auto-generated passwords
      - JUPYTERHUB_AUTOGENERATED_PASSWORD_DELIMITER=- # delimiter for auto-generated passwords
      # Docker spawner
      - JUPYTERHUB_NOTEBOOK_IMAGE=stellars/stellars-jupyterlab-ds:latest # user container image
      - JUPYTERHUB_NETWORK_NAME=jupyterhub_network # container network
      # GPU support
      - JUPYTERHUB_GPU_ENABLED=2 # 0=disabled, 1=enabled, 2=auto-detect
      - JUPYTERHUB_NVIDIA_IMAGE=nvidia/cuda:13.0.2-base-ubuntu24.04 # GPU detection image
      # User environment services
      - JUPYTERHUB_SERVICE_MLFLOW=1 # MLflow experiment tracking
      - JUPYTERHUB_SERVICE_RESOURCES_MONITOR=1 # system resources monitor
      - JUPYTERHUB_SERVICE_TENSORBOARD=1 # TensorFlow training tracker
      # Idle culler (disabled by default)
      - JUPYTERHUB_IDLE_CULLER_ENABLED=0 # 0=disabled, 1=enabled
      - JUPYTERHUB_IDLE_CULLER_TIMEOUT=86400 # seconds of inactivity before culling (default 24h)
      - JUPYTERHUB_IDLE_CULLER_INTERVAL=600 # check interval in seconds (default 10min)
      - JUPYTERHUB_IDLE_CULLER_MAX_AGE=0 # max server age in seconds (0=unlimited)
      - JUPYTERHUB_IDLE_CULLER_MAX_EXTENSION=24 # max hours users can extend session
      # Misc
      - TF_CPP_MIN_LOG_LEVEL=3 # TensorFlow verbosity
      - CERTIFICATE_DOMAIN_NAME=localhost # self-signed certificate domain
      - JUPYTERLAB_AUX_SCRIPTS_PATH=/mnt/shared/start-platform.d # admin-managed startup scripts for user environments
      - JUPYTERLAB_AUX_MENU_PATH=/mnt/shared/lab-utils.d # admin-managed custom menu definitions for JupyterLab
      - JUPYTERHUB_TIMEZONE= # IANA timezone (e.g. Europe/Warsaw), empty = UTC
      - JUPYTERHUB_LOGO_URI= # custom logo URI (file:// or http(s)://)
      - JUPYTERHUB_FAVICON_URI= # custom favicon URI (file:// or http(s)://)
      - JUPYTERHUB_LAB_MAIN_ICON_URI= # JupyterLab main icon (file:// or URL)
      - JUPYTERHUB_LAB_SPLASH_ICON_URI= # JupyterLab splash icon (file:// or URL)
    labels:
      # Enable proxy support from Traefik
      - "traefik.enable=true"

      # ⚙  Jupyterhub Service (8000)
      - "traefik.http.routers.jupyterhub-rtr.rule=Path(`/jupyterhub`) || PathPrefix(`/jupyterhub/`)"
      - "traefik.http.routers.jupyterhub-rtr.entrypoints=websecure"
      - "traefik.http.routers.jupyterhub-rtr.service=jupyterhub-svc"
      - "traefik.http.routers.jupyterhub-rtr.tls=true"
      - "traefik.http.services.jupyterhub-svc.loadbalancer.server.scheme=http"
      - "traefik.http.services.jupyterhub-svc.loadbalancer.server.port=8000"
    networks:
      - jupyterhub_network
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD-SHELL", "pgrep -f jupytehub > /dev/null || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 5s
    restart: unless-stopped

  ## watchtower for automatic docker image refresh
  ## exposing port to force docker to allow only one instance of service
  watchtower:
    container_name: ${COMPOSE_PROJECT_NAME:-stellars-jupyterhub-ds}-watchtower
    image: nickfedor/watchtower:latest
    labels:
      - "com.centurylinklabs.watchtower.enable=false" # exclude from self-updates
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:rw # to control docker and refresh images
    command: --cleanup --schedule "0 0 0 * * *" # daily at midnight UTC (6-field cron with seconds)
    security_opt:
      - seccomp:unconfined #optional
    depends_on:
      jupyterhub:
        condition: service_healthy 
      traefik:
        condition: service_started
    ports:
      - "9911:9911"
    networks:
      - jupyterhub_network
    restart: unless-stopped
    privileged: true

volumes:
  jupyterhub_data:
  jupyterhub_certs:
  jupyterhub_shared:
    name: jupyterhub_shared

networks:
  jupyterhub_network:
    name: jupyterhub_network