Andreas Niemann 6a29db386f feat(bootstrap): shared docker provider + foundation-net precursor (ADR-006)

Composition substrate for Wave 2 (T03+):
- lib/context.ts: one Docker-over-SSH provider + DeployCtx threaded to component
  factories; FOUNDATION_DOCKER_HOST override for ephemeral validation.
- lib/versions.ts: resolve pinned images from VERSIONS; FOUNDATION_ALLOW_UNPINNED
  for local validation when digests are still PIN_DIGEST.
- components/network.ts: foundation-net (CONTRACT_003 §3.1).
- index.ts: phase-orchestration entrypoint with dependsOn gates; Wave-2 slots.
- ADR-006: shared-provider + per-component-factory model (egg does not route its
  phased bootstrap through the monolithic vendored DockerDeployments).

Validated: pulumi up over Docker-over-SSH created+verified+destroyed foundation-net
on crunchy01 (x86_64); ephemeral, nothing persisted. tsc + preview clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-30 18:18:40 +02:00

3 KiB

Raw Blame History

ADR-006 — Bootstrap Composition Model: Shared Provider + Per-Component Factories

Date: 2026-06-30 Status: Accepted

Context

The vendored @olsitec/pulumi-docker DockerDeployments class (T02) is monolithic: its constructor takes the full provider map + a flat list of all containers and creates them together, with no mechanism for ordering between containers beyond the network. The foundation bootstrap, however, needs phase gates (PLAN-002 §2/§5): Vault must be operator init'd and unsealed between the data-plane and Forgejo consuming its secrets, and Forgejo must be healthy before runner registration/handover. Expressing those gates through the monolithic wrapper is awkward (it would create the provider/network multiple times and cannot interleave an imperative init step).

Decision

The bootstrap creates the shared docker.Provider and foundation-net once (bootstrap/lib/context.ts, bootstrap/components/network.ts), and each service is a pure factory in bootstrap/components/<svc>.ts with signature (ctx: DeployCtx) => <outputs> that creates its own docker.Container(s) against the shared provider/network. bootstrap/index.ts is the single composition point; phase gates are Pulumi dependsOn edges, not imperative sequencing, so pulumi up derives the order.

The vendored DockerDeployments is retained as the published @olsitec/pulumi-docker API for simple downstream (Layer-1) use — deploying a flat list of containers — but the egg does not route its phased bootstrap through it.

Validation override: FOUNDATION_DOCKER_HOST=ssh://user@host points the provider at a dev Docker host without editing committed config; FOUNDATION_ALLOW_UNPINNED=1 lets VERSIONS PIN_DIGEST placeholders fall back to tags for local validation only.

Consequences

Easier:

Phase gates (Vault init, Forgejo-before-handover) are natural dependency edges.
One file per service, each independently ownable by a Wave-2+ agent (clean parallelism).
Validated end-to-end: pulumi up over Docker-over-SSH created foundation-net on crunchy01 (172.30.0.0/24, attachable) and destroy removed it cleanly (2026-06-30).

Harder:

More explicit plumbing than the one-call wrapper (a shared ctx threaded through factories).
Two composition styles coexist (egg = direct; downstream = DockerDeployments) — documented here to avoid confusion.

Alternatives Considered

Route the whole bootstrap through DockerDeployments: rejected — cannot express phase gates or the imperative Vault-init step without recreating the provider/network per call.
Modify the vendored module to support phases: rejected — it must stay a faithful Stage-1 vendor (ADR-005) and remain useful as the simple downstream API; forking its behaviour now splits it.

Confidence

High — the model is implemented and the Docker-over-SSH path is proven against a real x86_64 host (crunchy01). Companion: CONTRACT_003, PLAN-002 §5.

3 KiB Raw Blame History