feat(notebooks): optional Docker launcher for Python notebook series

[FrancescoRosciano]

Summary

• New examples/notebooks/python/Dockerfile + docker-compose.yml build a Python 3.13-slim image with getpatter (pinned via PATTER_VERSION, default 0.5.4), JupyterLab, and the helper deps from pyproject.toml. Compose mounts the parent examples/notebooks/ tree at /notebooks so _setup.py still finds .env and fixtures/; ports 8888 (Lab) and 8765 (EmbeddedServer for T2/T4 cells) are published. env_file is marked required: false so §1 zero-key cells just work.
• _setup.py gains in_docker() (checks PATTER_NOTEBOOKS_IN_DOCKER=1 and /.dockerenv) and start_docker(*, build, detach, open_url) which shells out to docker compose up -d --build from the notebooks dir; no-ops when already inside the container or when the docker CLI is missing.
• All 12 Python notebooks get an optional markdown + commented code cell at the top — Run All on a fresh checkout still behaves identically because the launcher is commented by default.

Test plan

• cd examples/notebooks/python && docker compose config parses without warnings
• docker compose up --build opens JupyterLab at http://localhost:8888/lab/tree/01_quickstart.ipynb
• Run All on 01_quickstart.ipynb inside the container — §1 cells pass with zero keys
• On the host, uncomment _setup.start_docker() in cell 1 of any notebook → container starts, URL printed
• _setup.in_docker() returns True inside the container, False on host
• nbstripout still strips outputs cleanly across all 12 notebooks

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
patter-06b046ce	🟢 Ready	View Preview	Apr 28, 2026, 10:30 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[FrancescoRosciano]

Review fixes pushed (f9a9efb)

Multi-agent review completed (Python style, security, project conventions, SDK parity, silent-failure hunt). Per request, all MEDIUM findings escalated and fixed alongside the HIGH ones.

HIGH — fixed

• Loopback-only port maps — 127.0.0.1:8888:8888 and 127.0.0.1:8765:8765 in docker-compose.yml. JupyterLab is no longer LAN-reachable.
• Auth token by default — _setup._generate_jupyter_token() writes a 32-byte URL-safe secret to ~/.config/patter-notebooks/jupyter_token (mode 0o600) on first call and reuses it. Injected via JUPYTER_TOKEN env var; the Dockerfile CMD reads it from env. PATTER_NOTEBOOKS_NO_TOKEN=1 is the explicit opt-out.
• start_docker() -> bool — every early-return now returns False so callers can branch. subprocess.run(check=False, capture_output=True) surfaces stdout/stderr on compose failure instead of swallowing them.
• TS parity — _setup.py module docstring acknowledges the gap; tracking issue notebooks: port Docker launcher to TypeScript notebook series #80 filed.

MEDIUM (escalated → fixed)

• Non-root container — Dockerfile creates patter (UID 1000 default, override via PUID/PGID build args), drops --allow-root.
• Pinned deps — new requirements.txt with exact versions; Dockerfile installs from it.
• Version drift — PATTER_VERSION is now a build arg consumed from a single line in requirements.txt; release process should update both. Documented in DEVLOG.
• detach=False guard — refuses to launch (would hang the kernel) and returns False with a banner.

LOW — fixed

• in_docker() accepts 1/true/yes/on (case-insensitive).
• webbrowser and secrets hoisted to top-of-file imports.
• New tests/test_docker_bootstrap.py — 19 unit tests covering env parsing, every start_docker() early-return, command argv assembly, and token persistence. All green.

Open follow-up

• notebooks: port Docker launcher to TypeScript notebook series #80 — port the Docker launcher to the TypeScript notebook series (Deno or tslab kernel TBD).

[FrancescoRosciano]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}