Deployment Topology

Status

Active

Date

2026-04-28

Owners

• Platform Backend

Last Verified Commit

56362a7a

Local Stack Source

The canonical local deployment topology is the Compose stack in:

• servers_v2/docker-compose.yml

The stack is contract-tested by:

• servers_v2/tests/test_compose_contract.py

Infrastructure Services

Service	Purpose	Local Port
postgres	shared PostgreSQL runtime	5433
redis	shared Redis runtime and stream transport	6381
migrate	one-shot migration bootstrap	none

Application Services

Service	Local Port	Health Mode
gateway	8080	/health
player_service	8010	/health
wallet_service	8011	/health
game_service	8012	/health
rolling_service	8013	/health
promotion_service	8014	/health
agent_service	8015	/health
admin_service	8016	/health
recon_service	8017	/health

Worker Services

Worker	Purpose	Health Mode
wallet_worker	wallet outbox publishing + hourly ledger-vs-balance reconciliation	heartbeat file + readiness
rolling_worker	wallet-event consumer, outbox, expiry, completion retry	heartbeat file + loop freshness
promotion_worker	wallet-event consumer, settlement scheduler, saga recovery	heartbeat file + scheduler readiness
agent_worker	agent outbox publishing	heartbeat file
admin_worker	scheduled admin jobs	heartbeat file + scheduler job health
recon_worker	Pushbullet/Telegram/recon loops	heartbeat file + loop freshness
player_worker	player outbox publishing (ENABLE_OUTBOX_POLLER=true); player_service API has it disabled and depends_on: player_worker to guarantee the worker is healthy before traffic	heartbeat file

Current Split-Worker Rule

Services with dedicated background work run that work in a standalone worker so APIs can scale independently.

There are currently no exceptions: player_service runs its outbox loop in a dedicated player_worker (compose: player_service API has ENABLE_OUTBOX_POLLER: "false"; player_worker has it "true").

Environment Files

Local stack usage is designed around:

• servers_v2/.env.compose.example
• servers_v2/.env.compose.local

Sensitive values are intentionally env-driven and must not be committed into the Compose file.

Multi-Brand Mode

Per ADR-009, every brand runs on the same Compose stack:

• one postgres, one redis, one set of application services and workers
• brand identity is resolved per request from the request domain (or, for game callbacks, from the namespaced outbound account); no per-brand process duplication
• a MULTI_BRAND_ENFORCEMENT env var (off / observe / enforce) controls Gateway's JWT-vs-domain brand mismatch behavior; the repository compose default is now enforce, with observe reserved for explicit soak/rehearsal overrides

Recommended Local Validation

Use the local-stack runbook:

• docs/runbooks/local-docker/local-docker-full-stack.md