espn-ffb

espn-ffb is a project to query fantasy football data from ESPN's API and persist it in your own database. There is a very basic web component with a few views built using Flask that allows you to self-host your own fantasy football league page.

It should work with any databases supported by SQLAlchemy. You can change config.py to your respective database URI.

I have only tested with Postgres and the Docker image will also only work with Postgres.

Sample views:

• Recap - desktop, mobile
• Standings - desktop
• Head-to-head records - mobile
• Matchup history - mobile
• Playoffs - desktop

Setup

Two modes are supported:

• Run with Docker (easiest)
• Run locally (requires database instance)

Pre-requisites:

Run with Docker

• Docker

Run locally

• Python3
• PostgreSQL
• uWSGI (optional, but recommended if running in production)

Config:

Edit config.py with your own:

• Database credentials in DevConfig and ProdConfig.
• LEAGUE_ID
• swid (private leagues)
• espn_s2 (private leagues)

To find your swid and espn_s2 in Chrome, go to DevTools > Application > Cookies > https://fantasy.espn.com.

Run with Docker

Windows Users

There is a known issue with mounted volumes on Docker Desktop, so there are a couple additional steps to take.

1. Rename docker-compose.yml.windows to docker-compose.yml.
2. Create the docker volume pgdata.

   docker volume create --name=pgdata

Tested and working fine on Windows 10 with PowerShell 7.0.3 and Docker Desktop 2.3.0.5 48029.

Set up .env file

cp .env.sample .env

Edit .env and replace POSTGRES_PASSWORD with your preferred password.

Run

docker-compose up -d

Set up database

To set up the database the first time, you can run the following command:

docker-compose exec espn-ffb sh setup.sh

Open browser to http://localhost:5000.

Update

docker-compose exec espn-ffb sh update.sh

If you are running with Docker, stop here.

Run locally

Requirements:

pip3 install -r requirements.txt

Set up database:

python3 -m espn_ffb.setup -e {dev|prod}

Run:

# run with python3
python3 -m espn_ffb.app -e {dev|prod}

# run with uwsgi
uwsgi --http 0.0.0.0:5000 --ini conf/espn-ffb-{dev|prod}.ini

Open browser to http://localhost:5000.

Update:

python3 -m espn_ffb.db.update -e {dev|prod}

Deploy as Debian package

Build:

./gradlew clean build buildDeb -PbuildNumber=local

Install:

sudo dpkg -i build/distributions/espn-ffb*.deb

The .deb package includes two .service files:

• espn-ffb.service: Starts espn-ffb Flask app
• espn-ffb-update.service: Updates espn-ffb database

Recaps:

Sample recap templates as an example of how to structure written recaps.

Generate a new blank recap template:

python3 -m espn_ffb.scripts.generate_recap -e {dev|prod} -y {year} -w {week}

Contributors

• yorch - Thank you for the Docker support!
• smfarrelly - Thank you for converting the raw SQL to ORM and for the UI redesign!