Notebook (Jupyter) — Guia do Administrador

Dar Python aos analistas costumava significar instalar ambientes locais, distribuir credenciais por e-mail e perder o controle de onde os dados vão parar. Com o ambiente de Notebook do DATTA, cada analista ganha um Jupyter completo dentro da própria plataforma — mesma identidade, mesmo visual, acesso pronto às fontes de dados — e você mantém as credenciais e o isolamento sob controle central. Este guia cobre como habilitar o ambiente, o modelo de segurança das credenciais e o diagnóstico dos problemas mais comuns.

Público: administração e operação. Para o uso do notebook pelo analista, veja o Guia do Notebook e o

O que o analista recebe

• Jupyter Lab completo (notebook + terminal), acessível em Investigação›Notebook, sem nenhuma instalação local.
• Ambiente individual e isolado por usuário, criado sob demanda pelo JupyterHub.
• Conectores prontos para as fontes da plataforma — Neo4j, OpenSearch, Trino, cache da plataforma, MinIO e Spark Connect — com as credenciais de dados já injetadas no ambiente.
• Identidade única: não existe login separado. Quem está autenticado no DATTA entra no Notebook automaticamente.

Como a identidade viaja

O portal do Notebook pede à plataforma um cookie de sessão HttpOnly (datta_jwt), restrito ao caminho /jupyter. O autenticador do JupyterHub valida esse token (HS256, HS384 ou HS512), exige o perfil ANALISTA ou ADMIN e cria o usuário do hub a partir do e-mail normalizado — @ e . viram -. O endpoint que emite esse cookie está descrito na referência de API.

O tráfego de /jupyter/ vai direto ao proxy público do JupyterHub, na porta 8000; ele não passa pelo proxy de entrada da plataforma, que mantém uma rota equivalente apenas como contingência interna. Vale a atenção ao endereço interno correto: é jupyterhub-proxy-public:8000 — não existe um endereço chamado apenas jupyterhub. A variável de configuração JUPYTER_URL e o padrão usado pelo Copilot apontam para o proxy público.

Como habilitar em produção

1. Imagem do ambiente individual

A imagem jupyter-datta é construída a partir de docker/jupyter-datta/ (base quay.io/jupyter/minimal-notebook, mais os drivers de Neo4j, OpenSearch, Trino, cache da plataforma e MinIO, o Spark Connect e o tema DATTA). Ela é pinada pelo SHA de conteúdo da própria pasta, desacoplada do SHA do release Java:

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 <registro-de-imagens>/jupyter-datta:$TAG docker/jupyter-datta
podman push --tls-verify=false <registro-de-imagens>/jupyter-datta:$TAG

O tag é fixado em values-onprem-local.yaml, no campo jupyter.singleuser.image.tag. Nunca use um latest flutuante.

2. Configuração da instalação

values-onprem-local.yaml traz jupyter.enabled: true. As credenciais (jupyter.serviceToken, as chaves de MinIO e os demais segredos) vêm do arquivo .env — ou do release atual, por contingência — e são injetadas pelo script de release.

3. Implantação

Rode ./scripts/datta-release.sh (release uniforme). Ele sobe o hub, o proxy, os endereços internos, o cofre dedicado jupyter-user-secrets e a regra de roteamento de /jupyter/.

Modelo de segurança das credenciais

O ambiente de Notebook executa código arbitrário do analista. Por isso ele recebe credenciais de um cofre dedicado (jupyter-user-secrets), nunca o cofre de segredos da plataforma inteiro (datta-secrets).

O cofre dedicado contém somente o escopo "Dados + MinIO":

• NEO4J_PASSWORD
• OPENSEARCH_INITIAL_ADMIN_PASSWORD (e o alias OPENSEARCH_PASSWORD)
• MINIO_ACCESS_KEY
• MINIO_SECRET_KEY

Por que isso importa: o cofre da plataforma carrega JWT_SECRET, DATTA_VAULT_MASTER_KEY, GEMINI_API_KEY, DATTA_INTERNAL_TOKEN, ADMIN_DEFAULT_PASSWORD e outros. Um analista leria qualquer um deles com um os.environ de dentro de uma célula — expor o cofre inteiro seria vazamento de segredos da plataforma.

Duas decisões complementam o isolamento:

• Cofre estreito injetado por bloco, não chave a chave. O criador de ambientes não consegue mesclar listas de variáveis de ambiente: uma referência por chave apagaria a lista de variáveis que ele mesmo define. Por isso o cofre é estreito e injetado inteiro.
• Sem token de infraestrutura. O ambiente individual sobe sem montar automaticamente o token de conta de serviço do cluster — de dentro do notebook não há credencial de administração da infraestrutura.

Copilot cria notebooks (recurso opcional)

O Copilot do chat consegue criar notebooks .dattanb prontos no ambiente do usuário, usando a Contents API do Jupyter. Isso exige um service token do JupyterHub, registrado no hub com o escopo access:servers — um token do DATTA não é um token válido do JupyterHub.

• O token vem de JUPYTER_SERVICE_TOKEN, gerado pelo setup-datta.sh e persistido no .env.
• Sem ele, o hub não registra o serviço e a criação de notebook pelo Copilot fica desativada com aviso amigável — todo o restante do Notebook funciona normalmente.
• O script de release preserva jupyter.serviceToken entre releases, então a habilitação não se perde a cada implantação.

Diagnóstico rápido

Para saber mais

• Guia do Notebook — uso do notebook pelo analista. de notebooks.
• Perfis e permissões — de onde vêm os perfis ANALISTA e ADMIN.