Notebooks Hub Compose

Local deployment using Docker Compose. Full guide: deploy/Compose/README.md.

Run scripts with bash ./launch-notebooks-hub.sh from deploy/Compose (or bash deploy/Compose/launch-notebooks-hub.sh from the repo root). On Windows Git Bash, bind-mount paths are normalized automatically; set packages/API/.env paths with forward slashes (C:/Users/...). Use npm run start:api (Node launcher) and npm run start:ui — no MSYS_NO_PATHCONV in package.json.

Modes

Mode	Description
dev	Infrastructure in Docker; API and UI on the host (recommended)
local	Full stack in Docker — run node mode first
runtime	Full stack from pre-built Docker Hub images
node	One-off: install `node_modules` for `linux/amd64` (required before local/keycloak)
keycloak	Local stack plus Keycloak for OIDC testing
conda	Optional: install default Jupyter kernel
down	Stop containers and networks

Quick start — Dev

cp deploy/Compose/.env.example deploy/Compose/.env
cp packages/API/.env.example packages/API/.env
# Edit packages/API/.env paths (<repo-root> placeholders)

npm install   # repo root

bash deploy/Compose/launch-notebooks-hub.sh -m dev

npm run start:api   # repo root, terminal 1
npm run start:ui    # repo root, terminal 2

npm run start:api auto-exports FGA store/model IDs and the JupyterHub token. Sync modules once:

curl --location --request PUT 'http://127.0.0.1:8002/modules' --data ''

Launch Mode — Dev

Pre-launch

Copy .env files (see above).
npm install from repo root.
Optional: bash ./launch-notebooks-hub.sh -m conda for the default Jupyter kernel.

Launch

bash ./launch-notebooks-hub.sh -m dev

Then npm run start:api and npm run start:ui from the repo root.

Launch Mode — Local

Requires node mode first (installs linux/amd64 dependencies in a container):

bash ./launch-notebooks-hub.sh -m node
cp .env.example .env
bash ./launch-notebooks-hub.sh -m local

See deploy/Compose/README.md for -c / -s flags.

Launch Mode — Keycloak

Full local stack plus a local Keycloak OIDC IdP for auth testing. Requires node mode first. The launch script sets SERVICES_AUTH_* for Keycloak automatically.

bash ./launch-notebooks-hub.sh -m node
bash ./launch-notebooks-hub.sh -m keycloak

Service	URL
Notebooks Hub UI	http://localhost:4200
Keycloak admin	http://localhost:8082 (`admin` / `admin`)

Login: polusUser1 / password1 on the Keycloak sign-in page. Port 8082 is Keycloak; 8080 is OpenFGA.

See deploy/Compose/README.md for details.

Launch Mode — Runtime

Docker Desktop running, docker login.
Set UI_IMAGE_VERSION and API_IMAGE_VERSION in .env (defaults in .env.example).
Optional: -m conda for the default kernel.
Launch:

bash ./launch-notebooks-hub.sh -m runtime

Post-launch

Service	URL
JupyterHub	http://localhost:8000
Notebooks Hub UI	http://localhost:4200
Notebooks Hub API	http://localhost:8002

UI login (http://localhost:4200): username polus@example.com, password polus@example.com (use Local Test on the IdP page when auth is configured). Matches JUPYTERHUB_USER / -u if you override the default.

JupyterHub (http://localhost:8000) uses dummy auth — username only, no password on the Hub form.

Stop:

bash ./launch-notebooks-hub.sh -m down

Volumes persist under deploy/Compose/Volumes/. Full reset (including MongoDB and OpenFGA Postgres bind-mount data): ./clean-docker.sh from deploy/Compose, then relaunch your mode.

FAQ

Question	Answer
MongoDB `Authentication failed` after changing `.env`?	Delete `./Volumes/notebooks-hub_mongodb-data/` or run `./clean-docker.sh` — `MONGO_*` credentials only apply when the data directory is empty
When do I need `-m node`?	Before `local` or `keycloak`, and after dependency changes. For `dev`, use `npm install` on the host instead.
Where do FGA IDs come from?	`openfga-init` writes `Volumes/notebooks-hub_openfga/fga_variables.json`. `npm run start:api` reads them automatically in dev mode.
How does local auth work?	Leave `SERVICES_AUTH_` blank for no-auth offline use. Keycloak mode* (`-m keycloak`) sets auth env automatically.
Configurable variables?	.env.example and packages/API/.env.example.
New module install?	Rename/edit default-env.yaml, then re-launch.