ADR 0010: Deployment — containers, expand/migrate/contract, Kubernetes optional

Status: Accepted

Date: 2026-07-19

Context

First production release should be one well-structured deployment, not a Kubernetes prerequisite.

Decision

  • Deployable units: web, admin, control, api, worker containers + PostgreSQL, Redis, object storage, OTel collector. admin may deploy with web initially but stays a separate app boundary; control has stricter network/auth policy.
  • Migrations follow expand → backfill → contract; zero-downtime compatible; migration locks prevent concurrent runs.
  • Environment is validated at process start by @vercia/config; processes refuse to boot on invalid config.
  • Health/readiness endpoints + graceful shutdown with queue drain in the worker.
  • Kubernetes is an optional profile (infra/k8s), never required for local dev or first release.

Consequences

  • One VM + Compose can run the whole platform; horizontal scaling is adding API/worker replicas.