Notebook (Jupyter) — Administrator Guide

Giving analysts Python used to mean installing local environments, handing out credentials by e-mail and losing track of where the data ends up. With DATTA's Notebook environment, each analyst gets a full Jupyter inside the platform itself — same identity, same look, ready access to the data sources — while you keep credentials and isolation under central control. This guide covers how to enable the environment, the credential security model and how to diagnose the most common problems.

Audience: administration and operations. For analyst-facing notebook usage, see the Notebook Guide and the

What the analyst gets

• A full Jupyter Lab (notebook + terminal), reachable at Investigação›Notebook, with no local installation.
• An individual, isolated environment per user, created on demand by JupyterHub.
• Ready-made connectors to the platform's sources — Neo4j, OpenSearch, Trino, the platform cache, MinIO and Spark Connect — with the data credentials already injected into the environment.
• A single identity: there is no separate login. Whoever is authenticated in DATTA enters the Notebook automatically.

How the identity travels

The Notebook portal asks the platform for an HttpOnly session cookie (datta_jwt), scoped to the /jupyter path. The JupyterHub authenticator validates that token (HS256, HS384 or HS512), requires the ANALISTA or ADMIN role and creates the hub user from the normalized e-mail — @ and . become -. The endpoint that issues this cookie is described in the API reference.

Traffic to /jupyter/ goes straight to the public JupyterHub proxy on port 8000; it does not pass through the platform's entry proxy, which keeps an equivalent route only as an internal fallback. Mind the correct internal address: it is jupyterhub-proxy-public:8000 — there is no address named just jupyterhub. The JUPYTER_URL configuration variable and the default used by the Copilot both point to the public proxy.

How to enable it in production

1. Individual environment image

The jupyter-datta image is built from docker/jupyter-datta/ (base quay.io/jupyter/minimal-notebook, plus the Neo4j, OpenSearch, Trino, platform cache and MinIO drivers, Spark Connect and the DATTA theme). It is pinned by the content SHA of that folder, decoupled from the Java release SHA:

TAG=$(git rev-parse origin/main:docker/jupyter-datta | cut -c1-12)
podman build --tls-verify=false --platform linux/amd64 \
  -f docker/jupyter-datta/Dockerfile \
  -t <image-registry>/jupyter-datta:$TAG docker/jupyter-datta
podman push --tls-verify=false <image-registry>/jupyter-datta:$TAG

The tag is pinned in values-onprem-local.yaml, under jupyter.singleuser.image.tag. Never use a floating latest.

2. Installation configuration

values-onprem-local.yaml ships jupyter.enabled: true. The credentials (jupyter.serviceToken, the MinIO keys and the remaining secrets) come from the .env file — or from the current release, as a fallback — and are injected by the release script.

3. Deployment

Run ./scripts/datta-release.sh (uniform release). It brings up the hub, the proxy, the internal addresses, the dedicated jupyter-user-secrets store and the /jupyter/ routing rule.

Credential security model

The Notebook environment runs arbitrary analyst code. That is why it receives credentials from a dedicated store (jupyter-user-secrets), never the platform's entire secret store (datta-secrets).

The dedicated store holds only the "Data + MinIO" scope:

• NEO4J_PASSWORD
• OPENSEARCH_INITIAL_ADMIN_PASSWORD (and the OPENSEARCH_PASSWORD alias)
• MINIO_ACCESS_KEY
• MINIO_SECRET_KEY

Why this matters: the platform store carries JWT_SECRET, DATTA_VAULT_MASTER_KEY, GEMINI_API_KEY, DATTA_INTERNAL_TOKEN, ADMIN_DEFAULT_PASSWORD and others. An analyst could read any of them with an os.environ from inside a cell — exposing the whole store would leak the platform's secrets.

Two decisions complete the isolation:

• A narrow store injected as a block, not key by key. The environment spawner cannot merge environment variable lists: a per-key reference would wipe the variable list the spawner itself defines. Hence a narrow store, injected whole.
• No infrastructure token. The individual environment starts without automatically mounting the cluster's service-account token — from inside the notebook there is no infrastructure administration credential.

Copilot creates notebooks (optional feature)

The chat Copilot can create ready-made .dattanb notebooks in the user's environment, using Jupyter's Contents API. This requires a JupyterHub service token, registered in the hub with the access:servers scope — a DATTA token is not a valid JupyterHub token.

• The token comes from JUPYTER_SERVICE_TOKEN, generated by setup-datta.sh and persisted in .env.
• Without it, the hub does not register the service and notebook creation by the Copilot is disabled with a friendly notice — everything else in the Notebook works normally.
• The release script preserves jupyter.serviceToken across releases, so the enablement is not lost on every deployment.

Quick diagnosis

Learn more

• Notebook Guide — analyst-facing notebook usage. creation.
• Roles and permissions — where the ANALISTA and ADMIN roles come from.