Deploy JupyterHub using Helm

JupyterHub is an easy way to interact with a computing environment through a webpage. This tutorial guides you through deploying JupyterHub on Qovery using the official Helm chart.

Prerequisites

Existing Qovery cluster
Dedicated project and environment ready

Installation

Add JupyterHub Helm Repository

Navigate to your environment in Qovery Console
Add a new Helm repository:
- Repository name: JupyterHub
- Kind: HTTPS
- URL: https://hub.jupyter.org/helm-chart/

Create JupyterHub Service

Create a new Helm service with the following configuration:Basic Settings:

Application name: JupyterHub
Chart name: jupyterhub
Version: 3.3.7
Allow cluster-wide resources: Enabled

YAML Override:

proxy:
  service:
    type: ClusterIP

The type: ClusterIP configuration is necessary for JupyterHub to work properly within the Qovery cluster.

Add Network Configuration

Configure the service port:

Service name: jupyterhub-proxy-public
Service port: 80 (HTTP)
External port: 443
Port name: jupyterhub-proxy-public-p80

This configuration exposes JupyterHub’s proxy service externally through HTTPS.

Deploy Chart

Click the Play button to deploy JupyterHub:

Wait for the deployment to complete. This may take several minutes as JupyterHub pulls images and initializes.

Access JupyterHub

Once deployed, access JupyterHub via the Link button in the Qovery interface:

You’ll be directed to the JupyterHub login page.

Basic Configuration

Default Authentication

By default, JupyterHub uses a dummy authenticator that accepts any username/password. For production use, configure proper authentication.

Customize Your Deployment

This is a basic setup. For advanced configurations, consult:

Common Customizations

Configure Authentication

Use GitHub OAuth for authentication:

hub:
  config:
    JupyterHub:
      authenticator_class: github
    GitHubOAuthenticator:
      client_id: YOUR_CLIENT_ID
      client_secret: YOUR_CLIENT_SECRET
      oauth_callback_url: https://your-jupyterhub-url/hub/oauth_callback

Add YOUR_CLIENT_SECRET as a secret variable in Qovery.

Configure Resource Limits

Set resource limits for user notebooks:

singleuser:
  cpu:
    limit: 2
    guarantee: 0.5
  memory:
    limit: 2G
    guarantee: 1G

Enable HTTPS

HTTPS is automatically handled by Qovery. Just ensure your port configuration is correct.

Add Custom Docker Image

Use a custom notebook image:

singleuser:
  image:
    name: jupyter/datascience-notebook
    tag: latest

Configure Persistent Storage

Enable persistent storage for user notebooks:

singleuser:
  storage:
    type: dynamic
    capacity: 10Gi
    dynamic:
      storageClass: gp2  # AWS EBS

Accessing User Notebooks

Default Spawner

Users can spawn notebooks with different configurations:

Minimal environment
Data science stack (pandas, numpy, scipy)
TensorFlow/PyTorch for machine learning

Custom Profiles

Define multiple profiles for users:

singleuser:
  profileList:
    - display_name: "Minimal environment"
      description: "Basic Python environment"
      default: true
    - display_name: "Data Science"
      description: "Includes pandas, numpy, scipy"
      kubespawner_override:
        image: jupyter/datascience-notebook:latest
    - display_name: "Machine Learning"
      description: "TensorFlow and PyTorch"
      kubespawner_override:
        image: jupyter/tensorflow-notebook:latest
        cpu_limit: 4
        mem_limit: "8G"

Troubleshooting

Deployment stuck or failing

Check pod logs in Qovery Console
Verify cluster has sufficient resources
Ensure cluster-wide resources are enabled
Check for image pull errors

Cannot access JupyterHub

Verify the service port configuration
Check that the port name matches
Ensure HTTPS is properly configured
Check ingress logs for errors

Users cannot spawn notebooks

Check resource quotas on the cluster
Verify storage provisioner is working
Review user pod logs
Check for image pull errors

Notebooks losing data

Ensure persistent storage is configured
Verify PVC (PersistentVolumeClaim) is created
Check storage class is available
Review volume mount configuration

Scaling JupyterHub

Horizontal Scaling

Scale the hub component:

hub:
  replicas: 2

Resource Allocation

Adjust hub resources:

hub:
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 2
      memory: 2Gi

Helm Services

Learn about deploying with Helm

Advanced Settings

Configure service advanced settings

Environment Variables

Manage secrets and variables

Storage Configuration

Configure persistent storage

Get Started

Platform Capabilities

How-to Guides

Tutorials

Troubleshooting

Useful Resources

Deploy JupyterHub using Helm

Prerequisites

Installation

Basic Configuration

Default Authentication

Customize Your Deployment

Common Customizations

Accessing User Notebooks

Default Spawner

Custom Profiles

Troubleshooting

Scaling JupyterHub

Horizontal Scaling

Resource Allocation

Helm Services

Advanced Settings

Environment Variables

Storage Configuration

​Prerequisites

​Installation

​Basic Configuration

​Default Authentication

​Customize Your Deployment

​Common Customizations

​Accessing User Notebooks

​Default Spawner

​Custom Profiles

​Troubleshooting

​Scaling JupyterHub

​Horizontal Scaling

​Resource Allocation

​Related Documentation

Helm Services

Advanced Settings

Environment Variables

Storage Configuration

Prerequisites

Installation

Basic Configuration

Default Authentication

Customize Your Deployment

Common Customizations

Accessing User Notebooks

Default Spawner

Custom Profiles

Troubleshooting

Scaling JupyterHub

Horizontal Scaling

Resource Allocation

Related Documentation