# container-runtime Specification

## Purpose
TBD - created by archiving change setup-foundation. Update Purpose after archive.
## 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