User Guide

Installation

Recommended: create or activate a Python virtual environment.

uv add "jupyter-deploy[aws,k8s]" jupyter-deploy-tf-aws-eks-oidc

Or with pip:

pip install "jupyter-deploy[aws,k8s]" jupyter-deploy-tf-aws-eks-oidc

Project setup

mkdir my-eks-deployment
cd my-eks-deployment

jd init . -E terraform -P aws -I eks -T oidc

Consider making my-eks-deployment a git repository.

Configure and deploy

jd config
jd up

The first deployment takes approximately 25-30 minutes (EKS cluster creation, node provisioning, Helm chart installation, and OIDC provider registration).

Monitor cluster

# aggregated health check
jd health

# cluster control plane status
jd cluster status

# configure local kubeconfig
jd cluster login

Access workspaces

The web UI at the root of your domain lets users manage workspaces from the browser and download a kubectl setup script — see Web UI.

# open the web UI
jd open

# open a specific workspace
jd open --server-name my-workspace --scope default

Manage user workspaces

# list all workspaces
jd server list

# list workspaces in a specific namespace
jd server list --scope default

# check workspace status
jd server status --name my-workspace --scope default

# show workspace details
jd server show --name my-workspace --scope default

# stop a workspace
jd server stop --name my-workspace --scope default

# start a stopped workspace
jd server start --name my-workspace --scope default

# view workspace logs
jd server logs --name my-workspace --scope default

# execute a command in a workspace
jd server exec --name my-workspace --scope default -- ls /home/jovyan

# open an interactive shell
jd server connect --name my-workspace --scope default

Manage platform components

# health dashboard for all components
jd health --components

# list components
jd component list

# check a specific component
jd component status --name traefik

# view component logs
jd component logs --name dex

# restart a deployment (rolling restart)
jd component restart --name oauth2-proxy

# trigger a CronJob manually
jd component trigger --name jwt-rotator

# reconcile a HelmRelease (re-assert desired state, recreating deleted objects)
jd component reconcile --name workspace-router-chart

Take down

This operation removes all the resources associated with this project in your AWS account.

jd down