# 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: