# Contract — CONTRACT_003 — Container Network, DNS, Ports & Volumes

**Between**: all `bootstrap/components/*` that create containers ↔ each other (service discovery)
**Status**: Agreed (pending implementation validation)
**Realizes**: PLAN-002 §0 (Layer-0 = containers), §3 · **Uses**: `packages/pulumi-docker` (`DockerDeployments`)

## Interface

### 3.1 Network
- **Name**: `foundation-net` (Docker user-defined bridge — enables name-based DNS).
- **Subnet**: `172.30.0.0/24` (configurable, CONTRACT_001 `network.subnet`).
- **DNS**: containers reach each other by **container name** on `foundation-net`. No hardcoded IPs.

### 3.2 Containers, ports, exposure

| Container name | Image (digest in VERSIONS) | Internal port(s) | Published to host? | Reached by |
|----------------|----------------------------|------------------|--------------------|------------|
| `foundation-caddy` | caddy | 80, 443 | **Yes** 80/443 | the internet |
| `foundation-forgejo` | forgejo | 3000 (http), 22 (sshd) | SSH **yes** as `:2222`; HTTP **no** (via Caddy) | Caddy → 3000; git over `:2222` |
| `foundation-postgres` | postgres | 5432 | **No** (internal only) | forgejo |
| `foundation-rustfs` | rustfs | 9000 (S3 API), 9001 (console) | optional (S3 via Caddy) | forgejo, backup |
| `foundation-vault` | vault | 8200 | **No** (via Caddy, restricted) | pulumi, components |
| `foundation-runner` | act_runner | — (egress only) | **No** | registers to forgejo |
| `foundation-registry-cache` | registry:2 | 5000 | **No** (internal only) | runner (Docker Hub pull-through) |

**Exposure rule**: only Caddy publishes 80/443; Forgejo SSH is the one extra published port (`:2222`).
Everything else is **internal to `foundation-net`** (PLAN-002 §9.4). The runner SHOULD run on a
**separate privileged VM/network** (PLAN-001 §4a) — if co-located, fence it (NetworkPolicy-equivalent).

### 3.3 Internal endpoints (what components write into config/app.ini)
```
postgres:        foundation-postgres:5432
rustfs (S3):     http://foundation-rustfs:9000
vault:           http://foundation-vault:8200
forgejo (http):  foundation-forgejo:3000
registry cache:  http://foundation-registry-cache:5000
```

### 3.4 Named volumes (the stateful core — back these up, CONTRACT_004)

| Volume | Mounted by | Holds | Backup? |
|--------|-----------|-------|---------|
| `foundation-forgejo-data` | forgejo | **git repos** (POSIX FS — irreducible), app.ini, host SSH keys | **Yes — critical** |
| `foundation-postgres-data` | postgres | relational data (users, orgs, CI, package metadata) | **Yes** (via pg_dump) |
| `foundation-vault-data` | vault | raft storage | **Yes** (via raft snapshot) |
| `foundation-rustfs-data` | rustfs | blobs: LFS, packages, Actions artifacts | **Yes** (bucket-level) |
| `foundation-caddy-data` | caddy | ACME certs/account | recreatable (re-issue) — optional |
| `foundation-caddy-config` | caddy | autosave config | recreatable |

Volume root maps under CONTRACT_001 `dataRoot` (e.g. `/srv/foundation/<volume>`).

## Ownership
- `packages/pulumi-docker` provides the `DockerDeployments` primitive (name, image, ports, volumes,
  networks, envs) — vendored from olsicloud4 `modules/docker`.
- Each service component owns exactly one container definition + its volumes; the **network is owned
  by `network.ts`** and created first.

## Assumptions
- Single VM, single Docker daemon, RWO local volumes (no RWX — that's HA/Layer-1, PLAN-001 HA note).
- Container restart policy `unless-stopped`; Vault re-seals on restart → unseal helper (ADR-004).

## Validation
- After each component: `docker ps` shows the container healthy; an internal `curl`/`pg_isready`
  from a peer container resolves the name and connects.
- Only ports 443/80/2222 are reachable from off-host (assert with an external probe).

## Change Process
New service = add a row to §3.2 + §3.3, declare its volumes in §3.4, and (if external) justify the
published port. Renaming a container is breaking (it is the DNS name) — version this contract.