reactbin/specs/010-api-prod-dockerfile/research.md

Research: Production API Container Image

Decision 1 — Use a Separate Dockerfile.prod

Decision: Add api/Dockerfile.prod alongside the existing api/Dockerfile.

Rationale: The existing api/Dockerfile installs dev dependencies (.[dev]), mounts source with --reload, and is used by the Docker Compose integration test stack. Modifying it would break make test-integration. A separate file keeps the two images independent with zero coupling.

Alternatives considered:

• Build-arg flag in a single Dockerfile: adds conditional complexity and makes both files harder to read.
• Rename existing to Dockerfile.dev and make Dockerfile the production image: would require updating docker-compose.test.yml with an explicit file reference — a wider change than needed for this feature.

---

Decision 2 — Multi-Stage Build: uv Builder + python:3.12-slim Runtime

Decision: Two-stage build. Stage 1 (builder) uses ghcr.io/astral-sh/uv:python3.12-bookworm-slim to install production dependencies into a virtual environment. Stage 2 (runtime) uses python:3.12-slim and copies only the .venv and application source from the builder. uv is not present in the final image.

Rationale:

• uv's official Docker image is the fastest, most correct way to produce a pinned, bytecode-compiled venv from uv.lock.
• Keeping uv out of the runtime image reduces attack surface and image size.
• python:3.12-slim is a well-maintained, widely scanned base; using it for the runtime stage aligns with existing project images.

Layer caching strategy:

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project   ← cache hits when only source changes
COPY app/ ./app/                                       ← only reaches here on source changes

--no-install-project installs all listed dependencies without the project package itself. The project source is then copied separately. This means a source-only change reuses the dependency layer from cache.

Environment variables for optimal builds:

• UV_COMPILE_BYTECODE=1 — pre-compile .pyc files; slightly larger venv but faster cold starts.
• UV_LINK_MODE=copy — avoids hard-link issues when copying between image layers.
• UV_PYTHON_DOWNLOADS=never — ensures the builder stage uses the bundled Python, not a downloaded one.

Alternatives considered:

• Installing deps into the system Python (--system): rejected because it pollutes the base image and makes it harder to copy deps cleanly into the runtime stage.
• Using a single FROM python:3.12-slim with pip: slower builds, no lockfile pinning, no bytecode compilation step.

---

Decision 3 — Non-Root User (UID 1001, System User)

Decision: Create a system user appuser with GID/UID 1001 in the runtime stage. All owned files are chown-ed at COPY time using --chown=appuser:appgroup.

Rationale: Running as root inside a container is a container breakout risk. A numeric UID (rather than a named user that might not exist on the host) is required by some Kubernetes pod security admission policies. UID 1001 avoids collision with UID 1000 (the typical first interactive user on a Linux host) while remaining a predictable, inspectable value.

Alternatives considered:

• UID 1000: small risk of collision with host user when bind mounts are involved.
• USER nobody: nobody (UID 65534) works but its name and UID are not consistent across distros.

---

Decision 4 — SIGTERM Graceful Shutdown via uvicorn --timeout-graceful-shutdown

Decision: Use uvicorn's built-in --timeout-graceful-shutdown 30 flag. No process supervisor (tini, s6) is required.

Rationale: uvicorn handles SIGTERM natively when run as PID 1 in single-worker mode (the production Dockerfile runs one worker). On SIGTERM it stops accepting new connections, waits up to --timeout-graceful-shutdown seconds for in-flight requests to complete, then exits with code 0. No additional init system is needed.

Alternatives considered:

• tini: adds a small init shim that reaps zombies and forwards signals. Not necessary with a single uvicorn worker (no child processes to reap).
• Gunicorn + uvicorn workers: more complex; appropriate for multi-worker setups but the deployment platform (Kubernetes) scales horizontally via pod replicas rather than in-process workers.

---

Decision 5 — curl for HEALTHCHECK

Decision: Install curl (via apt-get --no-install-recommends) in the runtime stage and use it in the HEALTHCHECK directive.

Rationale: The existing dev Dockerfile already installs curl for the same reason. curl -f exits non-zero on HTTP errors, making it a reliable single-command health probe. A Python one-liner adds interpreter startup overhead (~100ms) per check; curl is ~5ms.

Alternatives considered:

• wget -q --spider: available on Alpine but not on Debian-slim by default; requires separate install.
• Python urllib.request: no extra install, but slower and adds noise to the process table during health checks.

---

Decision 6 — TDD Verification via Shell Script

Decision: Write api/tests/build/verify_production_image.sh before Dockerfile.prod. The script builds the image and runs behavioral checks (health endpoint, non-root user, clean SIGTERM exit). It is the "failing test" per §5.1.

Rationale: The production image is a build artifact, not Python business logic. pytest cannot test a Docker image without Docker-in-Docker, which the current CI stack does not support. A shell script run on the host (via make verify-prod) is the appropriate TDD vehicle for this artefact type.

Verification steps the script covers:

1. docker build -f api/Dockerfile.prod api/ → fails (red) until Dockerfile.prod exists.
2. Run container with required env vars; wait for health endpoint → GET /api/v1/health returns 200.
3. Inspect running process user → UID ≠ 0 (non-root).
4. Send SIGTERM to container; assert exit code 0 within 30s (graceful shutdown).
5. Assert dev packages are absent: pip show pytest inside container must return non-zero.

Alternatives considered:

• pytest with docker SDK: requires docker Python package and DinD in CI; rejected as over-engineered for a single-file build artifact.
• Manual verification only: rejected because §5.1 mandates automated failing tests before production code.