evotraders/deploy/production-deployment.md

Production Deployment

This is the recommended production deployment mode for the current repository.

Recommendation

Use:

• split FastAPI services
• systemd as the process supervisor
• nginx as TLS terminator and reverse proxy
• static frontend build served by nginx
• Docker-based skill sandbox

This matches the current architecture better than a monolithic process and is lower-risk than introducing Kubernetes at the current stage.

Why This Mode Fits Best

1. The repository already uses a split-service runtime model.
2. runtime_service is the correct control-plane entrypoint for starting and stopping Gateway subprocesses.
3. The Gateway is run-scoped and ephemeral, which fits systemd + subprocess management better than forcing everything into a single service binary.
4. Skill execution has security requirements; Docker sandboxing is the practical production default.

Service Layout

Component	Bind
agent_service	127.0.0.1:8000
trading_service	127.0.0.1:8001
news_service	127.0.0.1:8002
runtime_service	127.0.0.1:8003
gateway websocket	spawned by runtime_service
nginx	:80 / :443

Frontend

Recommended frontend mode:

cd frontend
npm ci
npm run build

Then point nginx root at:

/opt/bigtime/app/frontend/dist

This is preferred over running backend.apps.frontend_service in production, because static serving via nginx is simpler and more reliable.

Environment

Create a shared environment file, for example:

sudo mkdir -p /etc/bigtime
sudo cp .env /etc/bigtime/bigtime.env

Required production settings:

AGENT_SERVICE_URL=http://127.0.0.1:8000
TRADING_SERVICE_URL=http://127.0.0.1:8001
NEWS_SERVICE_URL=http://127.0.0.1:8002
RUNTIME_SERVICE_URL=http://127.0.0.1:8003

SKILL_SANDBOX_MODE=docker
SKILL_SANDBOX_MEMORY_LIMIT=512m
SKILL_SANDBOX_CPU_LIMIT=1.0
SKILL_SANDBOX_NETWORK=none
SKILL_SANDBOX_TIMEOUT=60

Also supply the required market/model API keys in the same environment file or through your secret-management system.

Data Persistence

Persist these paths on durable storage:

• runs/
• logs/ if you keep service logs on disk
• optional .env-backed secrets should not live inside the repo working tree

The key runtime source of truth is:

• runs/<run_id>/state/runtime_state.json
• runs/<run_id>/state/server_state.json
• runs/<run_id>/logs/gateway.log

nginx Pattern

Recommended routing:

• / -> static frontend
• /api/runtime/* -> 127.0.0.1:8003
• /api/dynamic-team/* -> 127.0.0.1:8003
• /api/trading/* -> 127.0.0.1:8001
• /api/news/* -> 127.0.0.1:8002
• /api/* -> 127.0.0.1:8000
• /ws -> gateway websocket

The checked-in nginx config should be treated as a starting point, not a full multi-service production config.

Operational Notes

• Use workers=1 for runtime_service unless you deliberately redesign the runtime manager around multi-process coordination.
• Keep the other API services stateless and scale them separately if needed.
• Monitor:
  • runtime_service
  • run-scoped gateway.log
  • Docker daemon health
• Rotate logs outside the app, e.g. with journald or logrotate.

Best Next Step

Deploy with:

• systemd units from deploy/systemd
• nginx in front
• one VM first

Only move to containers/orchestration after the runtime/gateway operational behavior is stable in that simpler topology.