Architecture

Containers

The application runs as a set of containerized services orchestrated by Docker Compose. Traefik acts as the reverse proxy — it handles TLS termination, routes incoming HTTPS requests, and delegates authentication decisions to OAuth2 Proxy via the ForwardAuth middleware. OAuth2 Proxy manages the full OAuth 2.0 flow with GitHub as the identity provider, handling redirects, token validation, and session cookies. Traefik forwards authenticated requests to the JupyterLab container. A Fluent Bit sidecar collects service logs and a logrotate container manages log retention on disk.

Authentication flow

On first visit, Traefik forwards the request to OAuth2 Proxy, which redirects the browser to GitHub for authentication. GitHub prompts the user to authorize the OAuth App, then redirects back to OAuth2 Proxy with an authorization code. OAuth2 Proxy exchanges the code for an access token, verifies the user’s identity against the configured allowlist, sets a session cookie, and lets the request through to JupyterLab. The session cookie authenticates subsequent requests without repeating the OAuth dance. See the OAuth2 Proxy GitHub provider documentation for details.