Skip to content

1.3 Local Infrastructure Stack (Docker Compose)

Sprint: Sprint 01 - Foundation
Feature ID: 1.3
Subtasks: 1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5, 1.3.6

Objective

Deliver "Local Infrastructure Stack (Docker Compose)" within Sprint 01 - Foundation.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 1.1.1
  • 1.3.1
  • 1.3.2
  • 1.3.3
  • 1.3.4
  • 1.3.5

Subtasks

1.3.1 PostgreSQL service and per-service databases

  • ID: 1.3.1
  • Title: Add PostgreSQL to Docker Compose with per-service databases
  • Description: Add a PostgreSQL 16 service to infra/docker/compose.yml with an init script creating one database/schema per domain service (identity, customer, product, order, subscription, usage, billing, payment, notification, ticket) and per-service credentials (ADR-006).
  • Business Purpose: Database-per-service isolation locally (NFR-15).
  • Inputs: ADR-006 (database strategy), analysis Section 7.1.
  • Outputs: Postgres service in compose, infra/docker/postgres/init/*.sql.
  • Acceptance Criteria:
  • docker compose up postgres starts; each per-service database is reachable with its own user.
  • Dependencies: 1.1.1
  • Complexity: M

1.3.2 Kafka (KRaft) and Schema Registry

  • ID: 1.3.2
  • Title: Add Kafka (KRaft mode) and Schema Registry to Docker Compose
  • Description: Add Kafka 3.7+ in KRaft mode (no ZooKeeper) and Confluent/Apicurio Schema Registry. Pre-create MVP topics matching the event catalog domains via an init container or documented auto-create policy (ADR-009, ADR-019).
  • Business Purpose: Event backbone for asynchronous domain integration (NFR-11, NFR-16).
  • Inputs: ADR-009, ADR-019, docs/architecture/event-catalog.md.
  • Outputs: Kafka + Schema Registry services in compose; topic bootstrap script.
  • Acceptance Criteria:
  • docker compose up kafka schema-registry starts; a test produce/consume round-trips.
  • Schema Registry REST endpoint responds on its configured port.
  • Dependencies: 1.1.1
  • Complexity: M

1.3.3 Debezium Kafka Connect for outbox CDC

  • ID: 1.3.3
  • Title: Add Debezium Connect and outbox connector template
  • Description: Add Kafka Connect with the Debezium PostgreSQL connector and an example outbox connector config that routes outbox-table rows to domain.event topics (ADR-005, ADR-009).
  • Business Purpose: Atomic DB-write-plus-publish delivery for the transactional outbox (ARC-05).
  • Inputs: ADR-005, ADR-009, PLATFORM-SPEC outbox section.
  • Outputs: Connect service in compose, infra/docker/kafka-connect/connectors/outbox-connector.example.json, registration script.
  • Acceptance Criteria:
  • Connect starts; the example connector registers against a service outbox table without error (validated later when a producing service exists).
  • Dependencies: 1.3.1, 1.3.2
  • Complexity: M

1.3.4 Redis

  • ID: 1.3.4
  • Title: Add Redis to Docker Compose
  • Description: Add Redis 7 used for cache-aside, gateway rate limiting, idempotency keys, and refresh- token blacklist (analysis Section 7.1, NFR-18).
  • Business Purpose: Caching, rate limiting, idempotency, token revocation backbone.
  • Inputs: analysis Section 7.1, ADR-011.
  • Outputs: Redis service in compose.
  • Acceptance Criteria:
  • docker compose up redis starts; redis-cli ping returns PONG.
  • Dependencies: 1.1.1
  • Complexity: S

1.3.5 Observability stack

  • ID: 1.3.5
  • Title: Add OpenTelemetry Collector, Tempo, Loki, Prometheus, Grafana
  • Description: Add the observability stack with an OTel Collector receiving OTLP and exporting traces to Tempo, logs to Loki, metrics to Prometheus; Grafana with provisioned datasources and a starter dashboard (ADR-012, NFR-07/08/09).
  • Business Purpose: Distributed tracing, centralized structured logging, and metrics from day one.
  • Inputs: ADR-012.
  • Outputs: Collector/Tempo/Loki/Prometheus/Grafana services in compose with provisioning files.
  • Acceptance Criteria:
  • docker compose up brings the stack healthy; Grafana lists Tempo, Loki, and Prometheus datasources as reachable.
  • Dependencies: 1.1.1
  • Complexity: M

1.3.6 Compose orchestration, healthchecks, and Makefile

  • ID: 1.3.6
  • Title: Unify infra stack with healthchecks and Make targets
  • Description: Add healthchecks and start-order dependencies to every compose service and provide infra/Makefile / root Makefile targets (infra-up, infra-down, infra-logs, infra-reset).
  • Business Purpose: One-command, reproducible local environment for all later sprints.
  • Inputs: 1.3.1-1.3.5.
  • Outputs: Finalized infra/docker/compose.yml, Makefile targets, infra/README.md.
  • Acceptance Criteria:
  • make infra-up brings the full stack to healthy; make infra-down removes it cleanly.
  • Dependencies: 1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5
  • Complexity: M

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • Postgres service in compose, infra/docker/postgres/init/*.sql.
  • Kafka + Schema Registry services in compose; topic bootstrap script.
  • Connect service in compose, infra/docker/kafka-connect/connectors/outbox-connector.example.json,
  • Redis service in compose.
  • Collector/Tempo/Loki/Prometheus/Grafana services in compose with provisioning files.
  • Finalized infra/docker/compose.yml, Makefile targets, infra/README.md.

Definition of Done

  • All subtasks (1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5, 1.3.6) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).