TASK: Define and lock minimal deployable backend/frontend image requirements #58

New Issue

darkhelm · 2026-06-17T19:28:19-04:00

darkhelm commented

2026-06-17 19:28:19 -04:00

Summary

Define explicit runtime requirements for backend and frontend deployable images and remove non-runtime tooling assumptions from deployable artifact definition.

Problem

Runtime artifact boundaries are not explicitly codified, which allows CI/tooling concerns to drift into deployable images.

Scope

Inventory runtime-only requirements for backend image.
Inventory runtime-only requirements for frontend image.
Define required runtime entrypoint, ports, health behavior, and environment contracts.
Document disallowed tooling classes in deployable images.

Out of Scope

CI workflow rewiring.
Test execution redesign.

Deliverables

Runtime requirements checklist for backend and frontend.
Clear deployable image contract for each service.
Decision notes on what must not be present in runtime artifacts.

Acceptance Criteria

Backend runtime requirements are documented and approved.
Frontend runtime requirements are documented and approved.
Runtime contracts include health endpoint expectations and startup behavior.
Non-runtime tool classes are explicitly excluded from deployable image definition.

Dependencies

Parent epic.

Definition of Done

Runtime artifact contract is clear enough that future tickets can enforce it automatically.

## Summary Define explicit runtime requirements for backend and frontend deployable images and remove non-runtime tooling assumptions from deployable artifact definition. ## Problem Runtime artifact boundaries are not explicitly codified, which allows CI/tooling concerns to drift into deployable images. ## Scope 1. Inventory runtime-only requirements for backend image. 2. Inventory runtime-only requirements for frontend image. 3. Define required runtime entrypoint, ports, health behavior, and environment contracts. 4. Document disallowed tooling classes in deployable images. ## Out of Scope 1. CI workflow rewiring. 2. Test execution redesign. ## Deliverables 1. Runtime requirements checklist for backend and frontend. 2. Clear deployable image contract for each service. 3. Decision notes on what must not be present in runtime artifacts. ## Acceptance Criteria 1. Backend runtime requirements are documented and approved. 2. Frontend runtime requirements are documented and approved. 3. Runtime contracts include health endpoint expectations and startup behavior. 4. Non-runtime tool classes are explicitly excluded from deployable image definition. ## Dependencies Parent epic. ## Definition of Done Runtime artifact contract is clear enough that future tickets can enforce it automatically.

darkhelm referenced this issue

2026-06-17 19:34:55 -04:00

EPIC: Separate deployable runtime images from CI validation environments #66

darkhelm added a new dependency 2026-06-17 19:35:40 -04:00

#66 EPIC: Separate deployable runtime images from CI validation environments

darkhelm changed title from ~~Define and lock minimal deployable backend/frontend image requirements~~ to TASK: Define and lock minimal deployable backend/frontend image requirements

2026-06-18 11:56:12 -04:00

darkhelm added the ops label 2026-06-18 11:57:44 -04:00

darkhelm added this to the E10 - Separate deployable runtime images from CI milestone 2026-06-18 11:58:27 -04:00

darkhelm added this to the Main Project Board project 2026-06-18 11:59:20 -04:00

copilotcoder was assigned by darkhelm

2026-06-18 11:59:52 -04:00

darkhelm added the afk devex task labels 2026-06-18 12:03:39 -04:00

darkhelm moved this to To Do in Main Project Board on 2026-06-19 09:23:47 -04:00

darkhelm moved this to In Progress in Main Project Board on 2026-06-19 09:25:04 -04:00

darkhelm commented

2026-06-19 09:34:19 -04:00

Plan: Lock Minimal Runtime Image Contracts (PP-58)

Define an explicit deployable runtime contract for backend and frontend images, document what is required versus forbidden in runtime artifacts, and align existing deployment docs/config references so future enforcement tickets can validate against a stable contract without changing CI workflow design in this issue.

Steps

Phase 1 - Baseline inventory (blocks all later phases): capture current runtime behavior from Docker and app entrypoints into a backend/frontend requirements matrix (entrypoint, exposed port, required env vars, health behavior, startup behavior, runtime dependencies, and artifact boundaries).
Phase 1 - Mark runtime vs non-runtime tool classes (parallel with step 1 once artifacts are inventoried): classify CI/test/lint/build tooling currently present in repository context as explicitly disallowed inside deployable runtime images.
Phase 2 - Write backend runtime contract (depends on 1,2): define minimal backend deployable image contract from existing behavior in Dockerfile.backend and backend/src/backend/main.py, including required env contract around DATABASE_URL and BACKEND_REQUIRED_PYTHON, expected startup fail-fast policy, and health endpoint expectations.
Phase 2 - Write frontend runtime contract (depends on 1,2; parallel with step 3): define minimal frontend deployable image contract from Dockerfile.frontend and frontend/nginx.conf, including static serving entrypoint, API proxy expectations, exposed HTTP port, and explicit runtime/non-runtime boundaries.
Phase 2 - Document forbidden classes (depends on 2): add a clear “not allowed in deployable images” section for CI runners, linters, test frameworks, package managers not needed at runtime, and build-time-only toolchains.
Phase 3 - Publish repository-level contract docs (depends on 3,4,5): add a dedicated runtime artifact contract doc and cross-link from existing operational docs so it is discoverable for future enforcement tasks.
Phase 3 - Record architectural decision (depends on 6): add an ADR that locks deployable image boundary policy and references parent epic linkage so future PRs can evaluate drift against accepted policy.
Phase 3 - Tighten doc consistency references (depends on 6,7): update README/development/CICD docs where deployable artifacts are described so terminology matches the new runtime contract.
Phase 4 - Acceptance mapping and sign-off checklist (depends on 6,7,8): include a direct AC-to-evidence table that maps each PP-58 acceptance criterion to exact document sections.
Phase 4 - Non-goals guardrails (depends on 9): explicitly state no CI workflow rewiring and no test-execution redesign in this issue, and push enforcement mechanics to follow-up tickets under epic #66.

Relevant files

/home/darkhelm/Projects/DarkHelm.org/plex-playlist/Dockerfile.backend — backend runtime base image, dependency install pattern, entrypoint, exposed port.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/backend/src/backend/main.py — startup validation behavior, health and compatibility endpoints, runtime policy semantics.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/backend/src/backend/database.py — database runtime env expectations and connectivity assumptions.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/Dockerfile.frontend — frontend production image stages, nginx runtime artifact boundary.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/frontend/nginx.conf — frontend runtime entry behavior, SPA routing, backend proxy contract.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/compose.yml — deploy-time service wiring and runtime service contract context.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/DEVELOPMENT.md — developer-facing operational guidance to align with runtime artifact definitions.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/README.md — top-level project contract summary and deployable artifact narrative.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/adr/ADR001-deterministic_runtime_policy.md — existing runtime-policy precedent to reuse language and decision framing.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/adr/ADR002-cicd_base_image_tagging.md — existing CI/runtime boundary framing to cross-reference.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs (new runtime contract doc path to be added during implementation) — canonical backend/frontend deployable image requirements checklist.
/home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/adr (new ADR to be added during implementation) — policy lock for runtime artifact boundaries.

Verification

Build an AC traceability checklist that maps PP-58 criteria to exact headings in the new runtime contract docs and ADR.
Validate backend documented health/startup contract against live code paths in backend/src/backend/main.py (lifespan startup validation, /health response semantics).
Validate frontend documented runtime contract against Dockerfile.frontend production stage and frontend/nginx.conf routing/proxy behavior.
Run a docs consistency sweep (repository text search) to ensure deployable/runtime terminology is consistent across README, docs/DEVELOPMENT.md, and ADRs.
Run markdown/doc linting checks already used in repo workflows if available, or at minimum ensure links/headings resolve and no contradictory statements remain.
Confirm documented exclusions explicitly call out CI/test/lint/build tool classes as non-runtime in deployable image definitions.

Decisions

Included scope: documentation and architecture-decision codification of minimal deployable runtime requirements for backend and frontend.
Included scope: explicit runtime contract for entrypoint, ports, health behavior, startup behavior, environment contract, and disallowed tooling classes.
Excluded scope: CI workflow rewiring, pipeline redesign, and test-execution redesign (per issue out-of-scope).
Excluded scope: broad operational hardening not required to define contract (for example observability stack redesign).
Dependency note: align language with parent epic #66 and keep this issue focused on contract definition so follow-up tickets can enforce automatically.

Further Considerations

Recommendation: define one canonical runtime-contract doc (single source of truth) and keep README/DEVELOPMENT as summaries to avoid contract drift.
Recommendation: in implementation, add a short “future enforcement hooks” section listing potential machine-check points (Dockerfile stage checks, compose schema checks) without implementing them in PP-58.
Recommendation: treat any mismatch between existing behavior and desired contract as explicit decision notes in the ADR, not silent assumptions.

## Plan: Lock Minimal Runtime Image Contracts (PP-58) Define an explicit deployable runtime contract for backend and frontend images, document what is required versus forbidden in runtime artifacts, and align existing deployment docs/config references so future enforcement tickets can validate against a stable contract without changing CI workflow design in this issue. **Steps** 1. Phase 1 - Baseline inventory (blocks all later phases): capture current runtime behavior from Docker and app entrypoints into a backend/frontend requirements matrix (entrypoint, exposed port, required env vars, health behavior, startup behavior, runtime dependencies, and artifact boundaries). 2. Phase 1 - Mark runtime vs non-runtime tool classes (parallel with step 1 once artifacts are inventoried): classify CI/test/lint/build tooling currently present in repository context as explicitly disallowed inside deployable runtime images. 3. Phase 2 - Write backend runtime contract (depends on 1,2): define minimal backend deployable image contract from existing behavior in Dockerfile.backend and backend/src/backend/main.py, including required env contract around DATABASE_URL and BACKEND_REQUIRED_PYTHON, expected startup fail-fast policy, and health endpoint expectations. 4. Phase 2 - Write frontend runtime contract (depends on 1,2; parallel with step 3): define minimal frontend deployable image contract from Dockerfile.frontend and frontend/nginx.conf, including static serving entrypoint, API proxy expectations, exposed HTTP port, and explicit runtime/non-runtime boundaries. 5. Phase 2 - Document forbidden classes (depends on 2): add a clear “not allowed in deployable images” section for CI runners, linters, test frameworks, package managers not needed at runtime, and build-time-only toolchains. 6. Phase 3 - Publish repository-level contract docs (depends on 3,4,5): add a dedicated runtime artifact contract doc and cross-link from existing operational docs so it is discoverable for future enforcement tasks. 7. Phase 3 - Record architectural decision (depends on 6): add an ADR that locks deployable image boundary policy and references parent epic linkage so future PRs can evaluate drift against accepted policy. 8. Phase 3 - Tighten doc consistency references (depends on 6,7): update README/development/CICD docs where deployable artifacts are described so terminology matches the new runtime contract. 9. Phase 4 - Acceptance mapping and sign-off checklist (depends on 6,7,8): include a direct AC-to-evidence table that maps each PP-58 acceptance criterion to exact document sections. 10. Phase 4 - Non-goals guardrails (depends on 9): explicitly state no CI workflow rewiring and no test-execution redesign in this issue, and push enforcement mechanics to follow-up tickets under epic #66. **Relevant files** - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/Dockerfile.backend — backend runtime base image, dependency install pattern, entrypoint, exposed port. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/backend/src/backend/main.py — startup validation behavior, health and compatibility endpoints, runtime policy semantics. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/backend/src/backend/database.py — database runtime env expectations and connectivity assumptions. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/Dockerfile.frontend — frontend production image stages, nginx runtime artifact boundary. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/frontend/nginx.conf — frontend runtime entry behavior, SPA routing, backend proxy contract. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/compose.yml — deploy-time service wiring and runtime service contract context. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/DEVELOPMENT.md — developer-facing operational guidance to align with runtime artifact definitions. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/README.md — top-level project contract summary and deployable artifact narrative. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/adr/ADR001-deterministic_runtime_policy.md — existing runtime-policy precedent to reuse language and decision framing. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/adr/ADR002-cicd_base_image_tagging.md — existing CI/runtime boundary framing to cross-reference. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs (new runtime contract doc path to be added during implementation) — canonical backend/frontend deployable image requirements checklist. - /home/darkhelm/Projects/DarkHelm.org/plex-playlist/docs/adr (new ADR to be added during implementation) — policy lock for runtime artifact boundaries. **Verification** 1. Build an AC traceability checklist that maps PP-58 criteria to exact headings in the new runtime contract docs and ADR. 2. Validate backend documented health/startup contract against live code paths in backend/src/backend/main.py (lifespan startup validation, /health response semantics). 3. Validate frontend documented runtime contract against Dockerfile.frontend production stage and frontend/nginx.conf routing/proxy behavior. 4. Run a docs consistency sweep (repository text search) to ensure deployable/runtime terminology is consistent across README, docs/DEVELOPMENT.md, and ADRs. 5. Run markdown/doc linting checks already used in repo workflows if available, or at minimum ensure links/headings resolve and no contradictory statements remain. 6. Confirm documented exclusions explicitly call out CI/test/lint/build tool classes as non-runtime in deployable image definitions. **Decisions** - Included scope: documentation and architecture-decision codification of minimal deployable runtime requirements for backend and frontend. - Included scope: explicit runtime contract for entrypoint, ports, health behavior, startup behavior, environment contract, and disallowed tooling classes. - Excluded scope: CI workflow rewiring, pipeline redesign, and test-execution redesign (per issue out-of-scope). - Excluded scope: broad operational hardening not required to define contract (for example observability stack redesign). - Dependency note: align language with parent epic #66 and keep this issue focused on contract definition so follow-up tickets can enforce automatically. **Further Considerations** 1. Recommendation: define one canonical runtime-contract doc (single source of truth) and keep README/DEVELOPMENT as summaries to avoid contract drift. 2. Recommendation: in implementation, add a short “future enforcement hooks” section listing potential machine-check points (Dockerfile stage checks, compose schema checks) without implementing them in PP-58. 3. Recommendation: treat any mismatch between existing behavior and desired contract as explicit decision notes in the ADR, not silent assumptions.

darkhelm commented

2026-06-19 10:25:01 -04:00

Implemented the documentation and policy-definition slice for PP-58.

What is now in place:

Added a canonical deployable runtime contract document covering backend and frontend runtime requirements.
Added an ADR that locks deployable runtime image boundary policy and scope guardrails for this issue.
Updated top-level project docs so the new contract is discoverable from the main developer entry points.
Updated stale workflow filename references in related CI/CD docs so they match the current repository state.

New documentation:

docs/DEPLOYABLE_RUNTIME_CONTRACT.md
docs/adr/ADR003-deployable_runtime_image_contract.md

Updated documentation:

README.md
docs/DEVELOPMENT.md
docs/CICD_MULTI_STAGE_BUILD.md
docs/SECURE_DOCKER_CICD.md
docs/CICD_TROUBLESHOOTING_GUIDE.md

What the new runtime contract now defines:

Backend deployable image boundary and required runtime base/process.
Frontend deployable image boundary and required runtime base/process.
Entrypoint, exposed port, startup behavior, and runtime health expectations for both services.
Backend runtime environment contract, including DATABASE_URL and BACKEND_REQUIRED_PYTHON.
Explicitly disallowed non-runtime tooling classes in final deployable artifacts.
Acceptance-criteria traceability back to PP-58.
Future enforcement hooks called out as follow-up work under epic #66, without rewiring CI in this issue.

Acceptance criteria coverage:

Backend runtime requirements are documented.
Frontend runtime requirements are documented.
Runtime contracts include startup and health behavior expectations.
Non-runtime tooling classes are explicitly excluded from deployable image definitions.

Notes:

This change is documentation/ADR only.
CI workflow rewiring remains out of scope here, per the ticket.
Test execution redesign remains out of scope here, per the ticket.

Implemented the documentation and policy-definition slice for PP-58. What is now in place: - Added a canonical deployable runtime contract document covering backend and frontend runtime requirements. - Added an ADR that locks deployable runtime image boundary policy and scope guardrails for this issue. - Updated top-level project docs so the new contract is discoverable from the main developer entry points. - Updated stale workflow filename references in related CI/CD docs so they match the current repository state. New documentation: - `docs/DEPLOYABLE_RUNTIME_CONTRACT.md` - `docs/adr/ADR003-deployable_runtime_image_contract.md` Updated documentation: - `README.md` - `docs/DEVELOPMENT.md` - `docs/CICD_MULTI_STAGE_BUILD.md` - `docs/SECURE_DOCKER_CICD.md` - `docs/CICD_TROUBLESHOOTING_GUIDE.md` What the new runtime contract now defines: - Backend deployable image boundary and required runtime base/process. - Frontend deployable image boundary and required runtime base/process. - Entrypoint, exposed port, startup behavior, and runtime health expectations for both services. - Backend runtime environment contract, including `DATABASE_URL` and `BACKEND_REQUIRED_PYTHON`. - Explicitly disallowed non-runtime tooling classes in final deployable artifacts. - Acceptance-criteria traceability back to PP-58. - Future enforcement hooks called out as follow-up work under epic #66, without rewiring CI in this issue. Acceptance criteria coverage: 1. Backend runtime requirements are documented. 2. Frontend runtime requirements are documented. 3. Runtime contracts include startup and health behavior expectations. 4. Non-runtime tooling classes are explicitly excluded from deployable image definitions. Notes: - This change is documentation/ADR only. - CI workflow rewiring remains out of scope here, per the ticket. - Test execution redesign remains out of scope here, per the ticket.

darkhelm moved this to Done in Main Project Board on 2026-06-19 17:01:56 -04:00

darkhelm closed this issue

2026-06-19 17:02:01 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Blocks

#66 EPIC: Separate deployable runtime images from CI validation environments

DarkHelm.org/plex-playlist

Reference: DarkHelm.org/plex-playlist#58