Deployment

Deployment

Package entry points

# All three are equivalent — pick whichever you prefer
python run.py
python -m arb_bot
# On Linux server the systemd service uses:
ExecStart=venv/bin/python run.py

Makefile shortcuts (from local machine)

Requires .env.deploy with DEPLOY_SSH_KEY, DEPLOY_USER (root), DEPLOY_HOST (187.127.181.8), DEPLOY_REMOTE_DIR (/opt/trading-bot). See Infra & Services for the full Docker reference.

Architecture Overview

The dashboard follows a modern decoupled architecture for better performance and interactivity:

• Frontend: A React Single Page Application (SPA) built with Vite and Tailwind CSS. Located in frontend/, built into public/dist/.
• Backend: A FastAPI server (dashboard_server.py) that provides real-time PnL, position tracking, and documentation metadata via REST APIs.
• Nginx Proxy: Acts as the entry point, serving static files and proxying API requests to the FastAPI backend.

Systemd Services

Two separate services run on the production server:

The token refresher unit template lives at scripts/token-refresher.service. The dashboard shows its last stored token health through /api/token/health.

Nginx Configuration

Nginx redirects all port 80 traffic, including direct IP requests, to https://portfolioplanner.online. The HTTPS server serves the SPA from /var/www/html/dist/ and proxies /api/* requests to localhost:8080. Configuration is maintained in scripts/nginx_dashboard.conf.

The dashboard server block includes 92.4.66.95, portfolioplanner.online, and www.portfolioplanner.online as accepted host names so domain traffic does not fall through to the default Nginx site.

Deployed documentation routes are not public. Requests to /docs/* use Nginx auth_request against /api/auth/nginx-check, which accepts only a valid dashboard session cookie. Unauthenticated users are redirected to /login before any docs route is served.

Dashboard Session Policy

Dashboard login is per-user Telegram OTP with an HttpOnly session cookie identifying a persisted, revocable session row (not a process-global singleton). Multiple users, and multiple sessions for the same user, remain valid concurrently — logging in again never invalidates another session, and logout revokes only the current one. See Multi-User Auth & RBAC for the full login flow, role model, and admin bootstrap.

MCP & Google linking

The self-service link flow is default-off. Runtime values belong only to the dashboard service; the Google OAuth credentials are bootstrap-time inputs and are deliberately blanked in every application container. Other services also receive blank/pinned-safe values so a shared env_file cannot accidentally enable linking or fail while parsing numeric TTLs.

The dashboard startup validator requires non-placeholder HMAC and client secrets (at least 32 characters), a valid stable Fernet key, secure cookies for HTTPS, secure URLs (localhost HTTP is the development exception), exact callback path, positive TTLs, issuer agreement, and issuer-origin token/JWKS overrides. It reports variable names only and never echoes values.

docker compose cp scripts/keycloak_bootstrap.sh keycloak:/tmp/bootstrap.sh
docker compose exec \
  -e AGENT_KEYCLOAK_ADMIN \
  -e AGENT_KEYCLOAK_ADMIN_PASSWORD \
  -e AGENT_PUBLIC_BASE_URL \
  -e KEYCLOAK_GOOGLE_CLIENT_ID \
  -e KEYCLOAK_GOOGLE_CLIENT_SECRET \
  -e DASHBOARD_MCP_LINK_CLIENT_ID \
  -e DASHBOARD_MCP_LINK_CLIENT_SECRET \
  -e DASHBOARD_MCP_LINK_REDIRECT_URI \
  keycloak bash /tmp/bootstrap.sh

The bootstrap always reconciles the base Agent Gateway realm. Linking resources use an all-or-none group: when all of KEYCLOAK_GOOGLE_CLIENT_ID, KEYCLOAK_GOOGLE_CLIENT_SECRET, and DASHBOARD_MCP_LINK_CLIENT_SECRET are absent, the Google IdP and dashboard client are skipped; partial configuration fails immediately. With all three present, re-running reconciles the Google IdP, rotates both client secrets, enforces PKCE S256, disables direct grants, service accounts, and token exchange, and installs a client protocol mapper that copies the identity_provider session note to the ID-token broker claim.