Saltar al contenido principal

Quickstart

Target: a fresh checkout of alphaswarm to a green backtest result in under 30 seconds of typing (plus first-time Docker image pull, which is unavoidable).

Prerequisites​

  • Docker Desktop or compatible engine running locally.
  • Python 3.11 and make on your PATH.
  • The repo cloned to disk.

One-paste quickstart​

# 1. Pull the canonical compose stack.
make dev

# 2. Wait for /readyz to return 200.
curl http://localhost:8000/readyz

# 3. Run the bundled example backtest.
docker exec alphaswarm-api python -m alphaswarm.cli.cli backtest \
    --config configs/strategies/momentum_demo.yaml \
    --start 2024-01-01 --end 2024-06-30

If the third command returns a JSON summary with non-zero sharpe and total_return, your dev stack is healthy.

What just happened​

  • make dev boots the canonical compose profile defined in alphaswarm_platform/deployments/compose/docker-compose.dev.yml. This brings up Postgres + Redis + the Iceberg REST catalog + alphaswarm-core (FastAPI) + alphaswarm-worker (Celery) + alphaswarm-beat.
  • curl http://localhost:8000/readyz confirms the FastAPI gateway is serving requests against a migrated Postgres schema. Migrations run automatically on first boot via the alphaswarm-api container's entrypoint.sh.
  • The backtest command dispatches a Celery task that pulls the example momentum strategy, runs it against the seeded data, and writes a backtest_runs ledger row.

Next steps​

  1. Want to see the run in the UI? Open http://localhost:3001 — that is the Vite operator UI (alphaswarm_client).
  2. Want to add your own strategy? Read Recipe: Add a strategy.
  3. Want to set up paper trading? Read Concept: paper trading followed by Tutorial: first paper trading session.
  4. Want to deploy this to Kubernetes? Read How-to: Kubernetes deploy.

If it does not work​

The /readyz probe is the single canonical health check. If it returns non-200 within 60 seconds:

  • Check docker compose logs alphaswarm-api for migration errors.
  • Confirm Postgres is reachable: docker exec alphaswarm-postgres pg_isready.
  • Confirm Redis is reachable: docker exec alphaswarm-redis redis-cli ping.
  • Verify the Iceberg REST catalog is up: curl http://localhost:8181/v1/config.

If the backtest command itself errors out, the most common cause is a stale Iceberg manifest from a prior dev cycle. Tear down with make down && docker volume prune -f and re-run.

For deeper debugging, see How-to: incident response.