Add dynamic analyst runtime updates and deployment guides

deploy/production-deployment.md

@@ -0,0 +1,134 @@
+# 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:
+
+```bash
+cd frontend
+npm ci
+npm run build
+```
+
+Then point `nginx` root at:
+
+```text
+/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:
+
+```bash
+sudo mkdir -p /etc/bigtime
+sudo cp .env /etc/bigtime/bigtime.env
+```
+
+Required production settings:
+
+```bash
+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](/Users/cillin/workspeace/evotraders/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.