88 lines
3.9 KiB
Markdown
88 lines
3.9 KiB
Markdown
# container-runtime Specification
|
|
|
|
## Purpose
|
|
Define the production container image for the application: a reproducible multi-stage FrankenPHP build serving the public directory, run in regular mode as a non-root user, shared by web/queue/scheduler processes, with no secrets in layers and a healthcheck on `/up`.
|
|
## Requirements
|
|
### Requirement: Production image uses multi-stage FrankenPHP build
|
|
|
|
The system SHALL provide a multi-stage Dockerfile that builds Composer dependencies, frontend assets, and a FrankenPHP runtime image serving `public/`.
|
|
|
|
#### Scenario: Image builds reproducibly in CI
|
|
|
|
- **WHEN** the `container` CI job builds the Docker image from a clean checkout
|
|
- **THEN** the build completes successfully and produces a runnable image
|
|
|
|
### Requirement: FrankenPHP runs in regular mode only
|
|
|
|
The system MUST NOT enable FrankenPHP worker mode in the MVP. The runtime SHALL use FrankenPHP in regular mode (ADR-006).
|
|
|
|
#### Scenario: Runtime configuration is regular mode
|
|
|
|
- **WHEN** the production image starts the web process
|
|
- **THEN** FrankenPHP serves requests in regular mode without worker persistence
|
|
|
|
### Requirement: Runtime image runs as non-root when supported
|
|
|
|
The system SHALL configure the production runtime to run as a non-root user when the base image supports it.
|
|
|
|
#### Scenario: Container process is non-root
|
|
|
|
- **WHEN** the web container is running in production configuration
|
|
- **THEN** the primary process MUST NOT run as root
|
|
|
|
### Requirement: Same image supports web queue and scheduler processes
|
|
|
|
The system SHALL use the same application image for web, queue worker, and scheduler processes with distinct commands (SPEC §15.2).
|
|
|
|
#### Scenario: Queue worker starts from application image
|
|
|
|
- **WHEN** the queue process is started with `php artisan queue:work`
|
|
- **THEN** it uses the same built image as the web process
|
|
|
|
### Requirement: Production image contains no secrets in layers
|
|
|
|
The system MUST NOT embed secrets, credentials, or private keys in Docker image layers.
|
|
|
|
#### Scenario: Image inspection finds no embedded secrets
|
|
|
|
- **WHEN** the image is built in CI
|
|
- **THEN** build arguments and layers MUST NOT contain production secrets or `.env` values
|
|
|
|
### Requirement: Container healthcheck validates application availability
|
|
|
|
The system SHALL define a container healthcheck that verifies application availability via the `/up` endpoint or equivalent boot check.
|
|
|
|
#### Scenario: Unhealthy container is detected
|
|
|
|
- **WHEN** the application inside the container fails to respond healthy on `/up`
|
|
- **THEN** the container healthcheck MUST report unhealthy status
|
|
|
|
### Requirement: Local Compose runs FrankenPHP application alongside PostgreSQL
|
|
|
|
The local Docker Compose stack SHALL include a FrankenPHP application service built from the project Dockerfile, dependent on a healthy PostgreSQL service, exposing the application on port 8000 (or documented equivalent). FrankenPHP MUST run in regular mode (ADR-006).
|
|
|
|
#### Scenario: Developer starts full local stack
|
|
|
|
- **WHEN** a developer runs `docker compose up -d` with the application service enabled
|
|
- **THEN** PostgreSQL and the FrankenPHP app containers MUST become healthy
|
|
- **AND** `GET /up` on the app port MUST return HTTP 200
|
|
|
|
#### Scenario: App waits for database readiness
|
|
|
|
- **WHEN** the application service starts
|
|
- **THEN** it MUST depend on the PostgreSQL healthcheck succeeding before becoming ready
|
|
|
|
### Requirement: Runtime PHP version is canonically 8.4
|
|
|
|
Docker, CI, and project documentation MUST treat PHP 8.4 as the canonical runtime for this MVP. Statements that require PHP 8.5+ MUST NOT remain in project docs while the runtime image uses 8.4.
|
|
|
|
#### Scenario: Dockerfile pins PHP 8.4
|
|
|
|
- **WHEN** the production/runtime image is built
|
|
- **THEN** the FrankenPHP base image MUST use PHP 8.4
|
|
|
|
#### Scenario: Documentation matches the runtime
|
|
|
|
- **WHEN** a contributor reads the README requirements
|
|
- **THEN** the documented PHP version MUST be 8.4 (compatible with Composer `^8.3`)
|