# 0011 · OCI containers, Podman first, three deployment strategies

**Status:** Accepted · 2026-09-22

## Context

CoDNA is self-hosted software. How it is installed is a feature, not an
afterthought — the people evaluating it are infrastructure engineers deciding
whether it is worth their afternoon.

Three constraints shaped this:

1. Companies running Docker Desktop at any scale need a paid license. An
   open-source project should not implicitly require one.
2. Teams already run Kubernetes, or they run a VM, or they want one host with
   Compose. All three are legitimate and none is the "real" way.
3. During development, Docker Desktop on this machine could not reach Docker Hub
   at all: DNS returned AAAA records and the host had no IPv6 default route.
   Podman's VM had no such problem. A stack that only works on one runtime is a
   stack that sometimes does not work.

## Decision

**Target OCI, not a vendor.** The build file is `Containerfile`, which podman,
docker, buildah, and kaniko all consume unchanged. The compose file is
`compose.yaml` following the Compose Specification, so `podman compose` and
`docker compose` both run it. No runtime-specific features are used anywhere.

**Podman is the documented default**, with docker shown alongside everywhere.
`make` takes `CONTAINER=docker` to switch.

**Three supported deployment strategies**, all running the same binary:

| Strategy | Artifacts |
|---|---|
| Compose | `compose.yaml`, with CoDNA itself behind an `app` profile |
| Kubernetes | `deploy/kubernetes/` raw manifests plus kustomization, and `deploy/helm/codna/` |
| VM / bare metal | `deploy/systemd/` unit, sandboxed, plus an env template |

**Migrations are embedded in the binary.** `codna migrate up` runs the schema
from a copy compiled in at build time.

## Consequences

- No deployment ever ships migration files or installs a migration tool, and the
  schema can never disagree with the binary running against it.
- The image is ~15 MB: a static binary on distroless, running as uid 65532 with
  a read-only root filesystem and no shell. There is nothing to exec into.
- Migrations run as a **Job** or `ExecStartPre`, never an initContainer on a
  multi-replica Deployment. goose takes no lock by default, so two replicas
  starting together could apply the same migration twice.
- Liveness and readiness are genuinely different endpoints. `/healthz` checks
  only that the process is up; making it check Postgres would turn a database
  blip into a restart of every pod, converting a recoverable dependency outage
  into an outage of CoDNA as well. `/readyz` checks dependencies so an unhealthy
  pod leaves the Service instead of serving errors.
- **The `local` storage driver pins a deployment to one replica.** Ingested
  originals need a writable volume, and ReadWriteOnce cannot be shared — hence
  `strategy: Recreate`. CoDNA is otherwise replica-safe: the outbox worker and
  scheduler both claim work with `FOR UPDATE SKIP LOCKED`. Scaling out needs
  ReadWriteMany or an object-store driver.
- The IANA timezone database is compiled into the binary (`_ "time/tzdata"`),
  because scheduled automations carry timezones and a distroless or scratch base
  may ship no zoneinfo.
- Three deployment paths are three things to keep working. Accepted: `make
  deploy-check` validates the manifests and the chart.

## Alternatives rejected

**Docker only.** Simpler documentation and the widest familiarity. Rejected on
the licensing question for commercial users, and because it failed outright on
the first machine this project was built on.

**Helm only, no raw manifests.** Fewer artifacts. Rejected because it forces
Helm on people who use kustomize, ArgoCD with plain manifests, or just
`kubectl apply`.

**Shipping Postgres and Typesense in the default Kubernetes install.** Friendlier
first run. Rejected as the default because a single-pod Postgres with no backups
or failover is the wrong place for a company's entire knowledge base; it is
available as an opt-in file for evaluation.

**Distributing only a container image.** Rejected because a VM with systemd is
still how a great many companies run internal tools, and a static Go binary
makes supporting that nearly free.