# GCS-DEPLOY-002 - Local Container Runtime Contract

Spec ID      : GCS-DEPLOY-002
Title        : Local Container Runtime
Version      : v1.0
Status       : Settled
Owner        : Phil
Approver     : Phil
Settled      : 2026-07-08
Depends on   : GCS-NAME-001, GCS-STACK-001, GCS-RUNTIME-001, GCS-TEST-001
Supersedes   : -

## 1. Current Phase

There is no active Docker Compose runtime in Phase 0. This contract reserves
names and failure rules so future local containers do not collide with other
projects on the workstation.

## 2. Namespace

| Object | Contract value | Rule |
| --- | --- | --- |
| Compose project | `gcs_project` | Every future local Compose command uses this project name. |
| Service prefix | `gcs-` | Every service/DNS name starts with this prefix. |
| Network | `gcs_project_net` | Explicit network name when a custom network exists. |
| Volume prefix | `gcs_project_` | Compose-created volumes carry this prefix. |
| Active compose path | `ops/docker/compose.gcs_project.yml` | Reserved; not present in Phase 0. |

Compose files must not set `container_name`. Compose-generated concrete names
prove project membership and avoid cross-project collisions.

## 3. Reserved Future Service Set

| Role | Compose service / DNS | Internal port | Host port | Status |
| --- | --- | --- | --- | --- |
| Static/web/API | `gcs-web` | `8000` | `8013` | Reserved |
| Database | `gcs-postgres` | `5432` | `5453` | Reserved |
| Object store | `gcs-object-store` | `9000` | `9023` | Reserved |

No `gcs-worker`, `gcs-scheduler`, `gcs-redis`, or `gcs-rabbitmq` service is
allowed while GCS-RUNTIME-001 forbids async queues.

## 4. URL Rules

Inside future containers:

```text
GCS_DATABASE_URL=postgresql://gcs_app:<secret>@gcs-postgres:5432/gcs
GCS_OBJECT_STORE_URL=http://gcs-object-store:9000
```

From the host workstation:

```text
GCS_DATABASE_URL=postgresql://gcs_app:<secret>@localhost:5453/gcs
GCS_OBJECT_STORE_URL=http://localhost:9023
```

Host-side `localhost` values belong only in host-local env files and tests
that explicitly run outside containers.

## 5. Forbidden Patterns

- Unscoped `docker compose up` that derives a project name from the directory.
- `container_name` in any GCS Compose file.
- Service names `db`, `postgres`, `redis`, `worker`, or `scheduler`.
- Hard-coded `localhost:5432`, `localhost:6379`, or `localhost:8000` in
  application source.
- Broker services while GCS-RUNTIME-001 is active.

## 6. Validation

Positive verification: `python3 -m tools.check_contracts --check` passes when
there is no active Compose file and no forbidden container tokens exist.

Negative verification: adding `container_name`, `gcs-redis`, `gcs-worker`, or
`localhost:5432` to an operational file fails the gate.