plex-playlist/docs/DEPLOYABLE_RUNTIME_CONTRACT.md

Deployable Runtime Image Contract

Purpose

Define the minimum deployable runtime contract for backend and frontend images. This document is the canonical source for what must be present, what must not be present, and what behavior deployment environments can rely on.

This contract supports issue PP-58 and establishes a baseline for future automation work under epic #66.

Scope

Lifecycle note:

• CI first builds deployable runtime artifacts in staging repositories (deployable-backend-staging, deployable-frontend-staging).
• After integration and E2E validation pass, CI promotes those immutable artifacts to release repositories (deployable-backend, deployable-frontend) via tag promotion.

Included:

• Backend deployable runtime image requirements.
• Frontend deployable runtime image requirements.
• Runtime entrypoint, ports, health behavior, startup behavior, and environment contracts.
• Explicitly disallowed non-runtime tooling classes in deployable images.

Excluded:

• CI workflow rewiring.
• Test execution redesign.
• New runtime hardening implementations not required to define contract.

Backend Runtime Contract

Runtime Artifact Definition

• Container build source: Dockerfile.backend.
• Build shape: two-stage build with a dependency stage and a minimal runtime stage.
• Runtime base image: python:3.14-slim.
• Runtime process: uvicorn backend.main:app --app-dir /app/src --host 0.0.0.0 --port 8000.
• Exposed runtime port: 8000.

Required Runtime Dependencies

The runtime artifact must include versions compatible with:

• fastapi==0.120.2
• psycopg==3.2.12
• sqlalchemy==2.0.44
• uvicorn==0.38.0

The lockfile in backend/uv.lock is the dependency source of truth.

Required Runtime Environment Contract

• DATABASE_URL is required.
  • Accepted form: postgresql://... or SQLAlchemy async form.
  • Runtime normalization to async psycopg dialect is performed in backend/src/backend/database.py.
• BACKEND_REQUIRED_PYTHON is optional and defaults to 3.14.

Backend Health and Startup Behavior

• Startup must fail fast if runtime policy checks fail.
  • Source: backend/src/backend/main.py lifecycle (lifespan) validation.
• Health endpoint contract:
  • GET /health returns 200 with {"status":"healthy","database":"connected"} when database probe succeeds.
  • GET /health returns 503 with {"status":"unhealthy","database":"disconnected"} when probe fails.
• Compatibility diagnostics endpoint:
  • GET /compatibility reports policy and package compatibility status.

Backend Runtime Checklist

• Runtime image built from Dockerfile.backend.
• Runtime process is uvicorn serving backend.main:app with app dir /app/src on 0.0.0.0:8000.
• DATABASE_URL is set in deployment runtime.
• GET /health behavior matches contract.
• Startup fails on runtime policy mismatch.
• Deployable artifact excludes CI-only and test-only tooling classes.

Frontend Runtime Contract

Frontend Runtime Artifact Definition

• Container build source: Dockerfile.frontend (target production).
• Build shape: two-stage build with a dependency/build stage and a minimal nginx runtime stage.
• Runtime base image: nginx:alpine.
• Runtime process: nginx -g "daemon off;".
• Exposed runtime port: 80.
• Runtime artifact payload: static assets from /app/dist copied to /usr/share/nginx/html.

Frontend Runtime Entry and Routing Contract

• Nginx configuration source: frontend/nginx.conf.
• SPA routing behavior must use fallback to index.html for unknown routes.
• API requests under /api/ are proxied to backend service endpoint http://backend:8000/ in compose deployments.

Frontend Health and Startup Behavior

• Startup expectation: nginx process starts and serves static assets on port 80.
• Runtime health expectation for deployment checks:
  • GET / should return 200 and serve frontend entry document.
• API proxy readiness is dependent on backend runtime availability.

Frontend Runtime Environment Contract

• No required runtime environment variables are defined for nginx static serving.
• Build-time frontend mode is production-oriented and not part of runtime env contract.

Frontend Runtime Checklist

• Runtime image built from Dockerfile.frontend production target.
• Runtime process is nginx serving on port 80.
• SPA route fallback behavior is present.
• /api/ proxy behavior aligns with backend service wiring.
• Deployable artifact excludes CI-only and test-only tooling classes.

Disallowed Tooling Classes in Deployable Runtime Images

Deployable runtime artifacts must not include tooling classes that are only needed for CI, validation, or local development workflows.

Disallowed classes:

• Linters and formatters (example: ruff, eslint, prettier).
• Type checking and static analysis tooling (example: pyright, vue-tsc).
• Test frameworks and test drivers (example: pytest, vitest, playwright).
• Browser test binaries and CI runner helper tools.
• Build-only package managers and build toolchains not needed at runtime.

Note:

• Multi-stage builds may use these tools in build stages.
• These tools must not be required by or present in final deployable runtime image layers.

Acceptance Criteria Traceability (PP-58)

1. Backend runtime requirements are documented and approved.
   • Covered by: "Backend Runtime Contract" and backend checklist.
2. Frontend runtime requirements are documented and approved.
   • Covered by: "Frontend Runtime Contract" and frontend checklist.
3. Runtime contracts include health endpoint expectations and startup behavior.
   • Covered by: backend health/startup section and frontend health/startup section.
4. Non-runtime tool classes are explicitly excluded from deployable image definition.
   • Covered by: "Disallowed Tooling Classes in Deployable Runtime Images".

Enforcement Hooks

Current enforcement implemented in CI:

• Dockerfile target boundary checks:
  • Script: scripts/check-dockerfile-boundaries.sh
  • Workflow: .gitea/workflows/cicd.yaml
• Deployable runtime image purity checks:
  • Script: scripts/verify-deployable-image-purity.sh
  • Workflow: .gitea/workflows/cicd.yaml
  • Checks include binary presence and profile-specific package metadata probes to detect CI/development tooling leakage.
• Runtime black-box integration checks against deployed backend container:
  • Workflow: .gitea/workflows/cicd.yaml (integration-tests job)
  • Inputs: deployable backend commit tag reference and immutable digest reference from main build dispatch.
  • Assertions: digest/tag consistency and live endpoint behavior for /, /compatibility, and /health on started runtime containers.

Future follow-up automation under epic #66 may expand this with:

• Contract tests that assert documented health/startup behavior.
• Additional policy checks for drift detection and broader runtime compliance.