跳到主要内容

Local Docker Full Stack

Status​

Ready

Date​

2026-04-22

Owners​

  • Platform Backend

Affected Services​

  • gateway
  • player_service
  • wallet_service
  • wallet_worker
  • game_service
  • rolling_service
  • rolling_worker
  • promotion_service
  • promotion_worker
  • agent_service
  • agent_worker
  • admin_service
  • admin_worker
  • recon_service
  • recon_worker
  • docs/architecture/deployment-topology.md
  • docs/architecture/migration-readiness.md
  • servers_v2/tests/test_compose_contract.py

Goal​

Start the full servers_v2 local stack in Docker, verify service and worker health, and run the baseline validation needed before deeper functional testing.

Preconditions​

  • Docker Desktop or compatible Docker Engine is running
  • Docker Compose is 2.24.0 or newer. The E2E override file uses the Compose !override tag to replace base service port bindings.
  • the following local ports are free:
    • 5433
    • 6381
    • 8080
    • 8010 through 8017
  • servers_v2/.env.compose.local exists
  • required secrets and local values have been filled from .env.compose.example
  • RGB_JWT_KID, RGB_JWT_PRIVATE_KEY, and RGB_JWT_PUBLIC_KEYS are set. Local env files may store PEM values with escaped \n newlines; production should still source keys from the managed secret store.
  • Before copying environment output into tickets or chat, inspect it through uv run python -m tools.dump_env_compose --redacted .env.compose.local from servers_v2/; never paste the raw file or non-redacted export output.
  • Treat this compose stack as a local verification topology. In the base compose file, gateway is the only host-facing app port; internal app ports, agent_service, admin_service, PostgreSQL, Redis, and MinIO are bound to 127.0.0.1. If an environment exposes agent or admin traffic outside the host, the production boundary must be an external ingress layer with VPN or firewall controls, TLS, authentication, rate limits, and allow-lists.

Startup Steps​

  1. Open the service directory.
    • cd servers_v2
  2. Render-check the stack if needed.
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.compose.local config
  3. Start the full stack with the dev overlay (source-code volume mounts + local bootstrap).
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.compose.local up -d --build
  4. Confirm all containers are up.
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml ps

Smoke Checks​

  • curl http://localhost:8080/health
  • curl http://localhost:8010/health
  • curl http://localhost:8011/health
  • curl http://localhost:8012/health
  • curl http://localhost:8013/health
  • curl http://localhost:8014/health
  • curl http://localhost:8015/health
  • curl http://localhost:8016/health
  • curl http://localhost:8017/health

Expected result:

  • APIs return healthy or OK responses
  • workers show healthy in docker compose -f docker-compose.yml -f docker-compose.dev.yml ps

Validation Steps​

  1. Confirm migrations ran successfully.
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml logs migrate --tail=100
  2. Confirm worker containers are healthy.
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml ps
  3. Check worker logs for repeated failure markers.
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml logs wallet_worker --tail=100
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml logs rolling_worker --tail=100
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml logs promotion_worker --tail=100
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml logs agent_worker --tail=100
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml logs admin_worker --tail=100
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml logs recon_worker --tail=100
  4. Run the Compose contract tests from the repo workspace.
    • cd /Users/saber/Dev/RGB/servers_v2
    • uv run pytest tests/test_compose_contract.py

E2E Validation​

Use the tracked non-production E2E env file so Docker Compose and pytest use the same internal service token.

  1. Start the E2E stack.
    • docker compose -p servers_v2_e2e --env-file tests/e2e/env.test -f docker-compose.yml -f tests/e2e/docker-compose.test.yml up -d --build
  2. Run the E2E suite.
    • NO_PROXY=localhost,127.0.0.1,::1 no_proxy=localhost,127.0.0.1,::1 uv run pytest tests/e2e/ -m e2e -v --timeout=120
  3. Tear down the E2E stack and volumes.
    • docker compose -p servers_v2_e2e --env-file tests/e2e/env.test -f docker-compose.yml -f tests/e2e/docker-compose.test.yml down -v

UI + Gateway E2E​

Run this when player-facing changes must prove the browser, web/thekingplus_logan, gateway CORS/domain routing, and live servers_v2 services together.

  • cd /Users/saber/Dev/RGB
  • make verify-servers-v2-ui-e2e

The target starts the tracked E2E Docker overlay, builds the UI in production mode with VITE_API_URL=http://localhost:18018/api/v1, runs Playwright against http://localhost:5004, covers registration/login, deposit, withdrawal, admin review/pay, signed wallet v2 bet/settle for withdrawable-cash setup, game launch, maintenance blocking, and tears down the stack with volumes.

Release Gate​

Do not treat the local stack as usable if any of the following is true:

  • a required API health endpoint is failing
  • a worker is running but not healthy
  • migrations did not complete
  • repeated loop failures appear in worker logs without recovery

Rollback Trigger​

Tear the stack down and fix configuration before proceeding if:

  • container health stays red
  • health endpoints never turn green
  • migrations fail
  • worker loops are clearly false-green or crash-looping

Rollback Steps​

  1. Stop the stack.
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml down
  2. Remove volumes only if a clean local reset is intended.
    • docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v
  3. Fix env or code issues.
  4. Re-run startup from the top.