跳到主要内容

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.

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

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.