feat(infra): add local-dev Docker Compose stack
CI / commits (pull_request) Successful in 1m4s
CI / check (pull_request) Successful in 1m12s
CI / scan (pull_request) Successful in 1m12s
CI / a11y (pull_request) Successful in 37s
CI / perf (pull_request) Successful in 1m29s

Bring up Postgres + Redis + OTel Collector in one command so
contributors can run the BFF end-to-end without each setting up
the runtime services manually. Replaces the throwaway
`docker run postgres:17-alpine` one-liner that was in §3 of
docs/development.md.

What lands:

- `infra/local/dev.compose.yml` — three core services
  (postgres 17.2-alpine, redis 7.4-alpine,
  otel/opentelemetry-collector-contrib 0.115.0) plus two
  viewers gated behind Compose profiles (pgweb under
  `--profile dbtools`, Jaeger 1.62 under
  `--profile observability`). All ports overridable via .env;
  state in named volumes; healthchecks on the data services.
- `infra/local/.env.example` — credentials + ports template.
  POSTGRES_PASSWORD and REDIS_PASSWORD are mandatory (compose
  refuses to boot without them); other keys default sensibly.
- `infra/local/init/postgres/01-init.sql` — bootstrap SQL per
  ADR-0013: `audit_owner` / `audit_writer` / `audit_reader` /
  `audit_archiver` roles plus `audit` schema, with default
  privileges encoding the append-only contract (INSERT to
  writer, SELECT to reader, DELETE to archiver, no UPDATE /
  TRUNCATE to anyone). Applied on first Postgres boot only;
  documented re-run procedure in infra/README.md.
- `infra/local/otel-collector.yaml` — pipeline: OTLP gRPC/HTTP
  → batch → debug exporter (always) + forward to `jaeger:4317`
  (no-op when the observability profile is off; logs warn-level
  retry but doesn't block other exporters).

Surrounding docs updated:

- `infra/README.md` — new "Local-dev stack" section with
  service inventory, port table, first-time setup, operational
  tips. The `local/` row replaces the previous placeholder.
- `docs/development.md` §3 — rewritten to walk through the
  compose-based setup; cross-links to `infra/README.md` for
  the full reference. Roadmap entry for "Local infra recipe"
  removed from §8 (now implemented); "Observability dev-loop"
  entry adjusted to point at the new Jaeger profile.

Production parity is intentionally left for the on-prem
infrastructure ADR (phase 3b) — this is the dev-only stack.
This commit is contained in:
Julien Gautier
2026-05-08 18:54:22 +02:00
parent a93ee16091
commit 6123953165
6 changed files with 390 additions and 37 deletions
+65
View File
@@ -0,0 +1,65 @@
# OpenTelemetry Collector config for the local-dev stack.
#
# v1 scope (per ADR-0012):
# - Accept OTLP from the BFF and the SPA on gRPC (4317) and HTTP
# (4318). The default OTEL_EXPORTER_OTLP_ENDPOINT in dev points
# here.
# - Batch + log everything to stdout via the `debug` exporter — the
# dev sees what their app emits without standing up a backend.
# - When the `observability` Compose profile is active, additionally
# forward to Jaeger (`jaeger:4317` on the internal Compose
# network). When the profile is inactive, the OTLP→Jaeger export
# fails at warn level but does not impact the debug pipeline.
#
# Production replaces the debug exporter with the proper backend
# (chosen in the future on-prem infrastructure ADR — likely Tempo +
# Loki + Mimir, or an OpenTelemetry-friendly all-in-one).
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch:
# Small batches in dev so the developer sees output quickly.
timeout: 5s
send_batch_size: 100
exporters:
debug:
verbosity: detailed
otlp/jaeger:
endpoint: jaeger:4317
tls:
insecure: true
sending_queue:
enabled: true
# When jaeger isn't running (profile off), retries fall back
# to a small queue rather than blocking the pipeline.
queue_size: 100
retry_on_failure:
enabled: true
initial_interval: 5s
max_interval: 30s
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [debug, otlp/jaeger]
logs:
receivers: [otlp]
processors: [batch]
exporters: [debug]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [debug]
telemetry:
logs:
level: info