ration/docker-compose.yml
caelum0x 92370eba5e feat(sdk,cli): self-serve API keys for Go SDK callers; fix(infra): docker-compose's missing AUTH_GRPC_ADDR/AUTH_ADDR broke every service but ledger-core
sdk/go/ration had no way to attach a credential, so its own README/doc.go
"Typical use" example was rejected with codes.Unauthenticated against any
default-config gateway (RATION_GATEWAY_REQUIRE_TENANT_AUTH defaults to
true) — nothing in this repo even called auth.IssueAPIKey before this.
Adds ration.WithAPIKey/WithBearerToken dial options (mirroring every
internal services/*/internal/authclient package's own interceptor
pattern) and a new `ration apikey issue` CLI command that actually mints
one via auth.IssueAPIKey. Verified live against a real running
auth+gateway+ledger-core+tenant-registry+card-issuance+webhook-ingestion
stack: no credential -> Unauthenticated, bad credential -> Unauthenticated
"invalid credential: not found", real minted credential -> IssueCard
succeeds end to end.

Also found, live, by actually running `docker compose up --build` for
real (not by reading code): gateway, card-issuance, tenant-registry,
webhook-ingestion, and agent all crash-looped forever in a plain
`docker compose up --build` — every one of them mints an operator JWT
from auth at startup and os.Exit(1)s if that fails, and none of their
compose service blocks set the env var each one's own config actually
reads (AUTH_GRPC_ADDR for all but gateway, which uniquely reads
AUTH_ADDR). Only ledger-core had this fixed previously (round 2). This
meant the entire containerized stack was non-functional end to end, not
just ledger-core's corner of it. Fixed all five; re-verified by tearing
the whole stack down and bringing it back up from scratch, seeding
tenants via `docker compose run --rm cli seed`, minting a real API key
via `docker compose run --rm cli apikey issue`, and issuing a card via
the Go SDK against the real containerized gateway on localhost:7002.

Also fixed a separate real bug in scripts/run-demo.sh's .env loader,
found live the same way: `IFS='=' read -r key value` silently drops a
single trailing IFS character, truncating any .env value ending in
exactly one '=' by one character — which is *every* `openssl rand
-base64 32` key (the exact command this repo's own docs recommend for
RATION_LEDGER_ENCRYPTION_KEY/AUTH_JWT_SIGNING_KEY), since a 32-byte
input always base64-encodes with exactly one padding '='. Reproduced
live: a real generated key crashed ledger-core at startup with
InvalidBase64(InvalidPadding) on a plain scripts/run-demo.sh run.
Switched to parameter-expansion splitting on the first '=' only;
re-verified the full run-demo.sh -> seed -> status cycle with a real
generated key, confirmed ledger.wal/ledger.db are genuine ciphertext
under the correct, untruncated key.

cargo test/go test/go vet all still pass (pre-existing, unrelated:
sdk/rust/ration-client's own #[cfg(test)] FakeGateway fixture doesn't
implement a newer Gateway trait method and fails to compile under
`cargo test` — a test-fixture-only gap, left alone per standing no-new-
test-work policy; production cargo build is unaffected).
2026-10-28 21:10:09 +03:00

458 lines
18 KiB
YAML

# One-command local multi-service dev stack — see
# docs/SCALE-EXPANSION.md section 3.
#
# docker compose up --build
#
# Brings up every deployable service wired together exactly like
# infra/terraform/envs/dev wires them in AWS: ledger-core is the
# single-writer ledger; auth, tenant-registry, card-issuance (in
# AIRWALLEX_MODE=mock, no real Airwallex credentials needed) and
# webhook-ingestion are the section-1 split services
# (docs/SCALE-EXPANSION.md section 1, docs/adr/0004); gateway is the
# thin BFF fanning out to all four, which is what agent/cli/tui actually
# dial — gateway.proto's external surface is unchanged by the split;
# audit-log is up as a standing service that ledger-core actually
# mirrors into — see services/ledger-core/src/audit_mirror.rs,
# docs/SCALE-EXPANSION.md section 8. gateway's own AUDIT_LOG_ADDR below
# is set but inert (see infra/terraform/README.md): ApplyEntry/
# RecordAgentDecision are both ledger-core RPCs, so every call gateway
# makes to them is already mirrored once, centrally, by ledger-core.
#
# AUTH_JWT_SIGNING_KEY has no default (services/auth/internal/config) —
# set it in a .env file next to this docker-compose.yml (e.g.
# `echo "AUTH_JWT_SIGNING_KEY=$(openssl rand -base64 32)" >> .env`,
# docker compose reads .env automatically) or export it in your shell
# before `docker compose up`; the auth service's entry below fails fast
# with a clear message if it's unset, matching Load()'s own behavior.
#
# services/tui and services/cli are interactive operator tools, not
# long-running services (same reasoning as infra/terraform/envs/*/main.tf
# and each of their own Dockerfiles) — they're defined below behind the
# "tools" profile so `docker compose up` never starts them, and you run
# them on demand against the rest of the stack instead:
#
# docker compose run --rm cli seed
# docker compose run --rm tui
#
# Observability stack (docs/SCALE-EXPANSION.md section 2) is wired in at
# the bottom of `services:` below: otel-collector receives every
# service's OTLP/gRPC traces (OTEL_EXPORTER_OTLP_ENDPOINT, set on every
# service below, points at it) and forwards them to jaeger; prometheus
# scrapes each Go service's own /metrics endpoint directly per
# infra/prometheus/prometheus.yml (metrics never flow through
# otel-collector); grafana is provisioned (infra/grafana/provisioning)
# with both as datasources plus a starter dashboard
# (infra/grafana/dashboards/ration-overview.json). None of this is a
# hard dependency for any of the app services — every exporter is
# fail-open (see pkg/telemetry's and
# services/ledger-core/src/telemetry.rs's doc comments): if you comment
# out the observability services below, the rest of the stack still
# starts and serves traffic exactly as before, just without traces/
# dashboards.
#
# open http://localhost:3000 (Grafana, admin/admin)
# open http://localhost:16686 (Jaeger UI)
# open http://localhost:9090 (Prometheus)
#
# ledger-core (Rust) exports traces here and now also exposes a
# /metrics endpoint (services/ledger-core/src/metrics.rs) scoped to the
# audit-mirror-failure counter docs/THREAT-MODEL.md's "Known gaps" #3
# names; it is not a full port of the Go services' per-RPC request/
# latency instrumentation yet — see docs/SLO.md's "ledger-core" section
# for that still-open, separately-scoped TODO.
#
# mTLS between services (pkg/mtls, infra/dev-ca/) is OFF by default here
# (every *_MTLS_ENABLED var below is unset/false, matching .env.example) —
# run infra/dev-ca/generate-dev-ca.sh, mount the generated certs into
# each service, and set the *_MTLS_* vars to turn it on for this stack.
services:
ledger-core:
build:
context: .
dockerfile: services/ledger-core/Dockerfile
image: ration/ledger-core:local
restart: unless-stopped
depends_on:
- otel-collector
- audit-log
- auth
ports:
- "7001:7001"
- "9099:9099"
environment:
LEDGER_CORE_ADDR: "0.0.0.0:7001"
LEDGER_CORE_METRICS_ADDR: "0.0.0.0:9099"
RATION_LEDGER_WAL_PATH: "/data/ledger.wal"
RATION_LEDGER_DB_PATH: "/data/ledger.db"
RUST_LOG: "info"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
# ledger-core mirrors every ApplyEntry/RecordAgentDecision
# outcome here, best-effort and async — see
# services/ledger-core/src/audit_mirror.rs,
# docs/SCALE-EXPANSION.md section 8.
AUDIT_LOG_ADDR: "audit-log:7003"
# REQUIRED — without this, src/main.rs's `env_or("AUTH_GRPC_ADDR",
# "localhost:7010")` default resolves to THIS container's own
# loopback (no listener there), not the `auth` service's: since
# RATION_LEDGER_REQUIRE_TENANT_AUTH defaults to true (see
# src/tenantauth.rs), ledger-core would start (the channel is
# lazy — see src/authclient.rs's doc comment) but every real
# tenant-scoped RPC would then fail its credential check against
# an unreachable address. `scripts/run-demo.sh` doesn't hit this
# because every service there runs on the same host, where
# `localhost:7010` really is `auth`'s bind address — only this
# compose network, where each service is its own namespace, needs
# the explicit service-name override every other direct
# ledger-core caller below (tenant-registry, card-issuance,
# webhook-ingestion) already has for `LEDGER_CORE_ADDR`.
AUTH_GRPC_ADDR: "auth:7010"
volumes:
- ledger_core_data:/data
# --- section-1 split services (docs/SCALE-EXPANSION.md section 1,
# docs/adr/0004): auth, tenant-registry, card-issuance and
# webhook-ingestion are each their own deployable here, independently
# scalable/restartable from the gateway BFF that fans out to them and
# from each other. Port numbering (7010-7013) matches each service's
# own internal/config doc comment. ---
auth:
build:
context: .
dockerfile: services/auth/Dockerfile
image: ration/auth:local
restart: unless-stopped
depends_on:
- otel-collector
ports:
- "7010:7010"
- "9098:9098"
environment:
AUTH_GRPC_ADDR: "0.0.0.0:7010"
AUTH_METRICS_ADDR: "0.0.0.0:9098"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
# No default (see services/auth/internal/config's doc comment) —
# a real deployment sets this from Secrets Manager
# (infra/terraform/modules/service/) or a .env file next to this
# docker-compose.yml, never a committed value. `docker compose up`
# fails fast here if it's unset, matching Load()'s own fail-fast
# behavior.
AUTH_JWT_SIGNING_KEY: "${AUTH_JWT_SIGNING_KEY:?set AUTH_JWT_SIGNING_KEY in a .env file or your shell, e.g. openssl rand -base64 32}"
tenant-registry:
build:
context: .
dockerfile: services/tenant-registry/Dockerfile
image: ration/tenant-registry:local
restart: unless-stopped
depends_on:
- ledger-core
- otel-collector
- auth
ports:
- "7011:7011"
- "9095:9095"
environment:
LEDGER_CORE_ADDR: "ledger-core:7001"
TENANT_REGISTRY_GRPC_ADDR: "0.0.0.0:7011"
TENANT_REGISTRY_METRICS_ADDR: "0.0.0.0:9095"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
# REQUIRED — same bug class as gateway's AUTH_ADDR/agent's and
# webhook-ingestion's AUTH_GRPC_ADDR below, found the same way
# (actually running `docker compose up --build`, not reading
# code): services/tenant-registry/internal/config reads
# AUTH_GRPC_ADDR (default "localhost:7010", this container's own
# loopback) to mint an operator credential at startup; without
# this, the service crash-loops on "connection refused" forever.
AUTH_GRPC_ADDR: "auth:7010"
card-issuance:
build:
context: .
dockerfile: services/card-issuance/Dockerfile
image: ration/card-issuance:local
restart: unless-stopped
depends_on:
- ledger-core
- otel-collector
- auth
ports:
- "7012:7012"
- "9096:9096"
environment:
AIRWALLEX_MODE: "mock"
AIRWALLEX_BASE_URL: "https://api-demo.airwallex.com"
LEDGER_CORE_ADDR: "ledger-core:7001"
CARD_ISSUANCE_GRPC_ADDR: "0.0.0.0:7012"
CARD_ISSUANCE_METRICS_ADDR: "0.0.0.0:9096"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
RATION_BRIDGE_MAX_FRACTION: "0.6"
RATION_BRIDGE_MIN_GRANT_MINOR_UNITS: "500"
RATION_BRIDGE_VELOCITY_WINDOW_HOURS: "24"
# REQUIRED — same bug class as gateway's AUTH_ADDR above, found
# the same way: services/card-issuance/internal/config reads
# AUTH_GRPC_ADDR (default "localhost:7010") to mint an operator
# credential at startup; without this, the service crash-loops.
AUTH_GRPC_ADDR: "auth:7010"
webhook-ingestion:
build:
context: .
dockerfile: services/webhook-ingestion/Dockerfile
image: ration/webhook-ingestion:local
restart: unless-stopped
depends_on:
- ledger-core
- otel-collector
- auth
ports:
- "7013:7013"
- "8081:8081"
- "9097:9097"
environment:
AIRWALLEX_WEBHOOK_SECRET: "${AIRWALLEX_WEBHOOK_SECRET:-}"
LEDGER_CORE_ADDR: "ledger-core:7001"
WEBHOOK_INGESTION_GRPC_ADDR: "0.0.0.0:7013"
WEBHOOK_INGESTION_HTTP_ADDR: "0.0.0.0:8081"
WEBHOOK_INGESTION_METRICS_ADDR: "0.0.0.0:9097"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
# REQUIRED — same bug class as gateway's AUTH_ADDR above, found
# the same way: services/webhook-ingestion/internal/config reads
# AUTH_GRPC_ADDR (default "localhost:7010") to mint an operator
# credential at startup; without this, the service crash-loops,
# which is why gateway's own webhookeventsclient then logged
# "name resolver error: produced zero addresses" retrying forever
# — webhook-ingestion was never actually up long enough to
# resolve.
AUTH_GRPC_ADDR: "auth:7010"
gateway:
build:
context: .
dockerfile: services/gateway/Dockerfile
image: ration/gateway:local
restart: unless-stopped
depends_on:
- ledger-core
- card-issuance
- webhook-ingestion
- otel-collector
- auth
ports:
- "7002:7002"
- "8082:8082"
- "9091:9091"
environment:
LEDGER_CORE_ADDR: "ledger-core:7001"
CARD_ISSUANCE_ADDR: "card-issuance:7012"
WEBHOOK_INGESTION_ADDR: "webhook-ingestion:7013"
GATEWAY_GRPC_ADDR: "0.0.0.0:7002"
# REQUIRED — found live by actually running `docker compose up
# --build`: without this, services/gateway/internal/config's
# getenvDefault("AUTH_ADDR", "localhost:7010") resolves to THIS
# container's own loopback (no listener there), not auth's.
# gateway is the one service in this repo whose own config reads
# "AUTH_ADDR" rather than every other service's "AUTH_GRPC_ADDR"
# (compare services/{auth,card-issuance,tenant-registry,
# webhook-ingestion}/internal/config, services/{cli,tui,agent}'s
# main.go — all "AUTH_GRPC_ADDR"; .env.example already documents
# gateway's "AUTH_ADDR" correctly at line ~96, this file just
# never matched it) — setting AUTH_GRPC_ADDR here first (an easy
# mistake, matching every sibling service) silently did nothing.
# Unlike ledger-core's lazy authclient channel (see ledger-core's
# own AUTH_GRPC_ADDR comment below), gateway's main.go calls
# authclient.MintOperatorJWT synchronously at startup (so it can
# present a credential on every RPC it forwards to ledger-core,
# which itself now enforces tenant auth — see
# services/ledger-core/src/tenantauth.rs) and os.Exit(1)s if that
# RPC fails — so gateway crash-looped forever ("connection
# refused", restart: unless-stopped retrying every few seconds)
# before this was set to the name gateway actually reads. This
# made the entire containerized stack's one public entrypoint
# (the service every other RPC in this file forwards through)
# completely non-functional on a plain `docker compose up
# --build`.
AUTH_ADDR: "auth:7010"
# internal/httpapi's REST/JSON facade (docs/SCALE-EXPANSION.md
# section 7, docs/adr/0003) dials this process's own gRPC
# listener above at GATEWAY_GRPC_DIAL_ADDR — "localhost:7002"
# reaches "0.0.0.0:7002" from inside this same container — then
# serves REST on GATEWAY_HTTP_ADDR:
#
# curl http://localhost:8082/v1/tenants/tenant_1/cards
GATEWAY_GRPC_DIAL_ADDR: "localhost:7002"
GATEWAY_HTTP_ADDR: "0.0.0.0:8082"
GATEWAY_METRICS_ADDR: "0.0.0.0:9091"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
RATION_RATELIMIT_RPS: "20"
RATION_RATELIMIT_BURST: "40"
RATION_RATELIMIT_SWEEP_INTERVAL_MINUTES: "10"
# Deliberately inert (see docker-compose.yml's top comment /
# infra/terraform/README.md): ApplyEntry/RecordAgentDecision are
# both ledger-core RPCs, so every call gateway makes to them is
# already mirrored once, centrally, by ledger-core's own
# audit_mirror. Set anyway for the day gateway needs a direct
# audit-log client of its own.
AUDIT_LOG_ADDR: "audit-log:7003"
agent:
build:
context: .
dockerfile: services/agent/Dockerfile
image: ration/agent:local
restart: unless-stopped
depends_on:
- ledger-core
- gateway
- otel-collector
- auth
ports:
- "9093:9093"
environment:
LEDGER_CORE_ADDR: "ledger-core:7001"
GATEWAY_GRPC_ADDR: "gateway:7002"
RATION_AGENT_METRICS_ADDR: "0.0.0.0:9093"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
RATION_AGENT_POLL_INTERVAL_SECONDS: "10"
RATION_AGENT_MODEL: "${RATION_AGENT_MODEL:-claude-sonnet-5}"
# REQUIRED — same bug class as gateway's AUTH_ADDR above, found
# the same way: services/agent/cmd/agent/main.go reads
# AUTH_GRPC_ADDR (default "localhost:7010") to mint an operator
# credential at startup; without this, the agent loop crash-loops
# and never polls for late deposits or grants bridge funding.
AUTH_GRPC_ADDR: "auth:7010"
# Without this, the agent starts and logs a warning (see
# services/agent/cmd/agent/main.go) but every LLM call it makes
# fails. Set it in a .env file next to this docker-compose.yml
# (docker compose reads .env automatically) or export it in your
# shell before `docker compose up` — never commit a real key here.
ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
audit-log:
build:
context: .
dockerfile: services/audit-log/Dockerfile
image: ration/audit-log:local
restart: unless-stopped
depends_on:
- otel-collector
ports:
- "7003:7003"
- "9092:9092"
environment:
AUDIT_LOG_GRPC_ADDR: "0.0.0.0:7003"
AUDIT_LOG_METRICS_ADDR: "0.0.0.0:9092"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
RATION_AUDIT_LOG_DATA_DIR: "/data"
volumes:
- audit_log_data:/data
# --- interactive operator tools (never started by `docker compose up`) ---
cli:
build:
context: .
dockerfile: services/cli/Dockerfile
image: ration/cli:local
profiles: ["tools"]
depends_on:
- ledger-core
- gateway
- auth
- audit-log
environment:
LEDGER_CORE_ADDR: "ledger-core:7001"
GATEWAY_GRPC_ADDR: "gateway:7002"
# REQUIRED — same bug class already fixed for ledger-core below
# (see that service's own AUTH_GRPC_ADDR comment): without this,
# main.go's envOrDefault("AUTH_GRPC_ADDR", "localhost:7010")
# resolves to this container's own loopback, not auth's, and
# every subcommand that mints an operator credential at startup
# (dialClients, i.e. every real command including `ration seed`)
# fails with "connection refused" before it ever reaches
# ledger-core or gateway. Found live: `docker compose run --rm
# cli seed` failed with exactly that error before this was added.
AUTH_GRPC_ADDR: "auth:7010"
# REQUIRED for `ration audit-check`, same reasoning — defaults to
# localhost:7003 otherwise.
AUDIT_LOG_GRPC_ADDR: "audit-log:7003"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
tui:
build:
context: .
dockerfile: services/tui/Dockerfile
image: ration/tui:local
profiles: ["tools"]
depends_on:
- ledger-core
- gateway
- auth
stdin_open: true
tty: true
environment:
LEDGER_CORE_ADDR: "ledger-core:7001"
GATEWAY_GRPC_ADDR: "gateway:7002"
# REQUIRED — identical bug/fix to cli's AUTH_GRPC_ADDR above: the
# TUI also mints an operator JWT from auth at startup
# (internal/authclient.MintOperatorJWT) before it can dial
# gateway at all.
AUTH_GRPC_ADDR: "auth:7010"
RATION_TUI_METRICS_ADDR: "0.0.0.0:9094"
OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
# --- observability stack (docs/SCALE-EXPANSION.md section 2) ---
otel-collector:
image: otel/opentelemetry-collector-contrib:0.116.1
restart: unless-stopped
command: ["--config=/etc/otel-collector-config.yaml"]
volumes:
- ./infra/otel-collector/config.yaml:/etc/otel-collector-config.yaml:ro
ports:
- "4317:4317" # OTLP gRPC — every service's trace exporter targets this
- "4318:4318" # OTLP HTTP
depends_on:
- jaeger
jaeger:
image: jaegertracing/all-in-one:1.62.0
restart: unless-stopped
environment:
COLLECTOR_OTLP_ENABLED: "true"
ports:
- "16686:16686" # Jaeger UI
prometheus:
image: prom/prometheus:v2.55.1
restart: unless-stopped
volumes:
- ./infra/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
- prometheus_data:/prometheus
ports:
- "9090:9090"
grafana:
image: grafana/grafana:11.3.1
restart: unless-stopped
depends_on:
- prometheus
- jaeger
environment:
GF_SECURITY_ADMIN_USER: admin
GF_SECURITY_ADMIN_PASSWORD: admin
GF_AUTH_ANONYMOUS_ENABLED: "false"
volumes:
- ./infra/grafana/provisioning:/etc/grafana/provisioning:ro
- ./infra/grafana/dashboards:/var/lib/grafana/dashboards:ro
- grafana_data:/var/lib/grafana
ports:
- "3000:3000"
volumes:
ledger_core_data:
audit_log_data:
prometheus_data:
grafana_data: