Installation and configuration
Before you install
Fantasy Project is an independent personal project. It is not affiliated with, endorsed by or sponsored by ESPN or The Walt Disney Company. "ESPN" is used only to say which service the project works with.
- Unofficial endpoints. The project works with ESPN Fantasy through undocumented endpoints and browser automation, not a public API. ESPN can change them at any time, so features can break without notice.
- Personal use only. Use your own ESPN account, on leagues you are a member of.
- No scraping. The project doesn't scrape ESPN. It isn't meant for collecting data about other leagues or other users, or for using ESPN at scale.
- Terms of service. Automating actions such as lineup changes, waiver claims, trades and draft picks may conflict with ESPN's terms of use. You are responsible for complying with them, and you use the project at your own risk.
- Rate and impact. The bots act on one league at the volume of a person managing their team: periodic syncs of that league's data and individual roster moves.
This section takes you from nothing to a running stack: core, the browser worker and the web UI, backed by Postgres, Redis and RabbitMQ. Start on your machine with every ESPN write disabled. Move to Kubernetes once you trust what the bots would do.
Which page do I need?
| You want to | Read |
|---|---|
| Run the services and their tests on your machine | Local development |
| Load your league and see the first recommendations | First run |
| Make sure nothing writes to ESPN | Run with every write disabled |
| Run the stack on your own cluster | Self-host on Kubernetes |
| Look up an environment variable | Configuration |
What will I be running?
| Component | Repository | Runtime | Port |
|---|---|---|---|
| Core API and jobs | fantasy-core-pipeline | Python 3.11 | 8000 |
| Browser worker | fantasy-browser-worker | Node 20 and Playwright Chromium | none; it consumes RabbitMQ |
| Web UI | fantasy-web-ui | Node 22 to build; nginx to serve | 5173 in development, 80 in the image |
| Manifests | fantasy-infra | Kustomize and Argo CD | — |
| Postgres, Redis, RabbitMQ | dev/compose.yaml locally; fantasy-infra on Kubernetes | Containers | 5432, 6379, 5672 (15672 for the RabbitMQ UI) |
On Kubernetes, oauth2-proxy signs you in with Google before anything reaches the UI. Locally there is no sign-in: the Vite dev server proxies /v1 straight to the API. For how the pieces fit together, see Architecture.
In what order?
- Local development: install each repo and start the dependencies.
- First run: migrate, ingest, refresh and capture the ESPN session.
- Run with every write disabled: check the dry-run settings before you start the worker.
- Self-host on Kubernetes, when you're ready.