Features

• Login with Keycloak (OIDC) or GitHub OAuth. Both issue the same DataLab JWT, sent as Authorization: Bearer <token> on every other endpoint.

• Provision a complete JupyterHub per environment type (ids, ipcc, dummy) in its own jupyterhub-<type> namespace: RBAC, secrets, config, storage, proxy, hub and ingress.

• Start and inspect each user’s Jupyter server through the JupyterHub REST API.

• Deploy a Kafka cluster (SASL/PLAIN) with a configurable number of brokers.

Requirements

• Python 3.12+

• uv

• Access to a Kubernetes cluster (~/.kube/config locally, or the in-cluster service account). Without it the API still starts, but cluster endpoints answer 503.

• A Keycloak realm and/or a GitHub OAuth app for login.

Quickstart

$ cp .env.example .env      # then fill in the values (see below)
$ uv sync
$ uv run uvicorn --factory datalab_api.main:app --reload

Open http://localhost:8000/docs for the interactive documentation.

datalab_api.main:app is an application factory, so use uvicorn --factory; fastapi dev cannot load it.

Configuration

All settings are read from environment variables or from a .env file. .env.example lists every option. The most relevant ones:

Never commit the real .env: keep secrets in the environment or in a Kubernetes Secret.

API

Users can only manage their own Jupyter server; ADMIN_USERS can manage everything.

Deployment in Kubernetes

$ kubectl create secret generic datalab-api-env --from-env-file=.env
$ kubectl apply -f datalab_api/manifests/api-deployment.yaml

The container image is built and published to the GitHub Container Registry by the workflow in .github/workflows.

Development

$ uv run pytest
$ uv run ruff format && uv run ruff check --fix
$ uv run mypy

Credits

Developed by the Advanced Computing and E-Science Group at IFCA. See AUTHORS.rst.