Deploying under your domain

The whole platform is one Python process (FastAPI + SQLite + the market engine and settlement loop).

git clone <this repo> && cd prop-sim
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env         # edit XGM_DOMAIN etc.
set -a; . ./.env; set +a
xgames serve --port 8000     # or: uvicorn xgames.main:app --port 8000

Open http://localhost:8000.

Configuration (environment)

XGM_GENESIS, XGM_KERNEL, XGM_SEED and the engine config are frozen into the database at first start (market_meta). Starting with different values against the same database is refused, because the recorded history would no longer match its menus. Use a fresh XGM_DB_PATH instead.

First start and the history load

On first start the platform serves immediately and a background thread loads the pre-launch history into the record, newest sessions first: for every session it generates the menu, executes the desk's legacy policy, realises each trade's demand path and stores the trades and statistics. Six months across the four markets is roughly 26,000 sessions and 4 million trades; expect 5–15 minutes (the platform stays responsive meanwhile) and a database of roughly 1 GB. Progress is shown at /console/timeline and /api/v1/markets/{id}/coverage. xgames backfill runs the same job synchronously (useful before packaging a demo).

Docker

docker build -t xgames .
docker run -p 8000:8000 -e XGM_DOMAIN=desk.example.com -e XGM_SCHEME=https \
  -e XGM_SECRET_KEY=$(openssl rand -hex 32) -v xgames-data:/data xgames

Put any TLS-terminating proxy (Caddy, nginx, Cloudflare) in front and point it at port 8000.

Publishing the docs to GitHub Pages

The same Markdown in docs/ is rendered in-app at /docs and is a ready MkDocs site:

pip install mkdocs mkdocs-material
mkdocs serve          # preview
mkdocs gh-deploy      # publish to the gh-pages branch

.github/workflows/docs.yml deploys automatically on push to main. Replace https://t5market.com placeholders by setting XGM_DOMAIN before building (mkdocs.yml uses a hook) — or leave them; in-app rendering substitutes them.

Updates and restarts

All state — accounts, cards and charges, open and funded orders, positions, carts, agents and API keys, the market record — lives in the SQLite database, so a restart never loses anything. Orders that were awaiting funding stay payable until their session closes; sessions that closed while the platform was down are processed in order on the next start (funded orders fill, unfunded ones expire, positions advance).

Code updates that change the schema are applied automatically at startup (xgames migrate runs the same step by hand): new tables and columns are added in place with defaults, new indexes are created, and the few changes SQLite cannot make in place are done as table rebuilds that copy the data. Applied steps are listed in schema_migrations and summarised in /api/v1/manifest under schema. Renames of the market engine are recognised (the recorded identity is migrated); a genuinely different engine, seed or genesis against an existing database is still refused.

Login sessions survive restarts too: if XGM_SECRET_KEY is not set, a key is generated once and stored next to the database (xgames.secret). Back up that file together with the database.

Recommended update procedure: stop the service, deploy the new code, start it. Take a copy of the database file first if you want a rollback point.

Operations

• Single process, single settlement thread: do not run more than one instance against the same database.
• xgames markets prints the market clocks; xgames menu m15 --tick N dumps a menu.
• Backups: copy the SQLite file (and xgames.secret) while the service is stopped, or use sqlite3 xgames.db ".backup copy.db" while it runs.