[Docker]

Docker

Abstract

Containers package the Pro API (Flask + evaluator) for reproducible local runs and Cloud Run deploys. A single multi-stage Dockerfile exposes named targets; Docker Buildx Bake (docker-bake.hcl) drives local loads and multi-platform release builds. Compose wires volume mounts and optional Redis/LSP profiles for desk development, with a production overlay for gunicorn.

Conceptual model

Interface surface

Dockerfile targets

All targets: Python 3.12-slim, non-root appuser (uid 1000), API_KEY_STORE=/data/api_keys.json, MPLBACKEND=Agg, healthcheck via curl (HTTP targets).

Buildx Bake (docker-bake.hcl)

# Local load (host platform)
docker buildx bake api                 # production image → pynescript-api:latest
docker buildx bake                     # default group: api + api-dev
docker buildx bake all                 # api + api-dev + lsp

# Multi-platform (amd64 + arm64). Set REGISTRY to push:
REGISTRY=gcr.io/$PROJECT/pynescript TAG=$COMMIT_SHA docker buildx bake release

Make wrappers:

make docker-build       # bake api
make docker-build-all   # bake all targets
make docker-buildx      # bake release (multi-platform)

One-time multi-platform builder (if needed):

docker buildx create --use --name pynescript

Compose

cp .env.example .env   # optional overrides

make docker-up         # api-dev on host :5002
make docker-up-full    # + redis profile (api + redis)
make docker-prod       # requires ADMIN_TOKEN; gunicorn, no source mounts
make docker-smoke      # curl http://127.0.0.1:5002/
make docker-down

# stdio LSP (not a long-running compose service)
docker compose --profile lsp run --rm lsp

Network name: pynescript-dev.

Production overlay (docker-compose.prod.yml): target api, volumes: !override so only api_data:/data remains (dev source binds are dropped), SQLite key store on /data, mem/cpu caps, requires ADMIN_TOKEN.

Environment variables

Cloud Build image tags

From cloudbuild.yaml (builds --target api):

gcr.io/$PROJECT_ID/pynescript/pynescript-pro-api:$COMMIT_SHA
gcr.io/$PROJECT_ID/pynescript/pynescript-pro-api:latest

Internals

Build stages

1. base — slim image, curl + freetype/png for matplotlib Agg, appuser, /data
2. builder — build-essential, pip cache mounts, install backend/requirements.txt then pip install ".[lsp]" into /install (requires pyproject.toml, README.md, LICENSE, NOTICE, src/, backend/)
3. runtime — copy prefix + sources, PYTHONPATH=/app/src:/app so compose mounts override site-packages
4. api / api-dev / lsp — final CMDs and healthchecks

.dockerignore

Keeps context small by excluding tests/ (corpus), docs/, brand/, node modules, compiler *.nbc/*.nbi caches, venvs, and IDE cruft.

Compose healthchecks

API: curl -fsS http://127.0.0.1:8080/. Redis: redis-cli ping.

Invariants & edge cases

1. Host port 5002 vs container 8080. AXIS local docs assume API on 5002 via compose; Cloud Run uses 8080.
2. Read-only mounts in compose mean dependency changes need image rebuild; source edits are visible via PYTHONPATH precedence.
3. Production target is immutable — no live mounts; use the prod overlay or Cloud Run.
4. Non-root appuser cannot write arbitrary paths; keep API_KEY_STORE under /data.
5. Cloud Build always builds --target api (gunicorn). Do not point it at api-dev.
6. LSP is stdio — not an HTTP service; use docker compose run --rm lsp rather than expecting a published port.

Worked examples

Production-like local API (bake)

docker buildx bake api
docker run --rm -p 8080:8080 \
  -e FLASK_ENV=production \
  -e ALLOWED_ORIGINS=http://localhost:8081 \
  pynescript-api:latest
curl -s http://127.0.0.1:8080/ | jq .

Compose with Redis

docker compose --profile redis up --build

Optional LSP container

docker compose --profile lsp run --rm lsp

Production overlay

export ADMIN_TOKEN=change-me
docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build -d

Failure modes

See also

• GCP
• Security
• Pro API lifecycle
• Local development