Skip to content
bflo.sh

ADR-0003: DDEV + PostgreSQL 16 + Redis as environment baseline

ADR-0003 — Accepted (template baseline). Part of the platform's decision record.

Adapted from the repo's docs/adr/0003-ddev-postgres-redis-baseline.md — Part of Internals: the platform's design set, published as content on the platform it describes.

  • Status: Accepted
  • Date: template baseline
  • Deciders: platform-engineer, contract-owner
  • Tiers affected: infra
  • Related: ADR-0004 (application stack), infra/README.md

Context

Every project spun from this template needs a reproducible local environment with fixed data-store semantics, identical for every engineer and agent, beneath the fixed application stack (ADR-0004). The team standard for local orchestration is DDEV.

Decision

We will run every project from this template on DDEV, with PostgreSQL 16 as the DDEV-managed system of record and Redis (official ddev/ddev-redis add-on) for cache, ephemeral state, and queue workloads. The frontend runs in a dedicated frontend (Node 22) DDEV service. Topology is bootstrapped by infra/ddev/bootstrap.sh; the resulting .ddev/ directory is committed.

Alternatives considered

  1. Raw docker-compose — more flexible, but re-solves routing, TLS, and DX that DDEV provides; rejected for a template meant to minimize friction.
  2. MySQL/MariaDB baseline — DDEV's default, but PostgreSQL is the chosen system of record for this template line; rejected.
  3. Deferring Redis until needed — the AsyncAPI boundary and Laravel queues assume a message substrate from day one; rejected.

Consequences

  • Every engineer and agent develops against identical service semantics; "works on my machine" is out of scope. Environments outside DDEV are unsupported until a CI ADR says otherwise.
  • Members may assume PostgreSQL 16 + Redis in any design without asking.
  • Baseline version bumps (PostgreSQL, Redis, Node) are new ADRs plus adoption tasks announced by platform-engineer.

Compliance

  • infra/ddev/bootstrap.sh is the only sanctioned way to create .ddev/; hand-rolled topologies are rejected in review.
  • Verify: ddev start boots green with postgres:16, the redis service, and the frontend service present (ddev describe).