Local setup
The backend runs in Docker. The steps are: start it, load some Shows (seed them from Steve’s page, or run a real ingest), export the data, then run the site from the export.
Start the backend
cp backend/.env.example backend/.env# edit backend/.env: set GOOGLE_MAPS_API_KEY (see Configuration)
docker compose up --build -dThe API starts at http://localhost:8000/graphql. Tables are created automatically on first boot, and the database
starts empty. The SQLite DB and FAISS indices are persisted in ./data/ on the host. See
Configuration for every setting.
Seed from Steve’s page
The quickest way to get Shows: no keys, and one request, for Steve’s page (no Google Places, MusicBrainz or embeddings, so Venues have no address, and Bands no genres, photos or Similar Bands).
docker compose exec api python -c "from app.database import Base, SessionLocal, enginefrom app.ingestion.steve_list import fetch_list, list_showsfrom app.ingestion.upsert import upsert_shows
Base.metadata.create_all(bind=engine)db = SessionLocal()shows = upsert_shows(db, list_shows(fetch_list().text))db.commit()print(f'Upserted {len(shows)} shows')db.close()"Then query at http://localhost:8000/graphql:
{ shows(limit: 5) { date venue { name city } acts { band { name } } isRecommended } }Run an ingest by hand
A real ingest needs the key above (and, for Last.fm and Discogs lookups, theirs) and the Ollama models. It looks every new Band up on the services, so the first one takes a long time.
Pull the Ollama models (one-time): the embedding model, and the genre model that
judges whether a tag is a genre (app/ingestion/genre_filter.py; needs Ollama 0.35 or later, so
docker compose pull ollama first if yours is older):
docker compose exec ollama ollama pull nomic-embed-textdocker compose exec ollama ollama pull tev1:0.8bRun the ingest (daily maintenance, then the List as Steve’s page has it now; the API server doesn’t schedule anything, the hourly check is a GitHub Action). How ingestion works has the steps:
docker compose exec api python -m app.cli ingestIf you have Ollama running locally already, remove the
ollamaservice fromdocker-compose.ymland addOLLAMA_BASE_URL=http://host.docker.internal:11434to.env.
Run the site
The site is built from static JSON exported from the database, not the API. Export it
into frontend/export/ (gitignored; read at build time, not published) whenever the data changes, then run the
frontend. It needs Node 22.12 or newer.
docker compose run --rm -v "$PWD/frontend/export:/export" api python -m app.cli export --out /exportrm -rf frontend/public/images && cp -R data/images frontend/public/images # Band photos; skip if data/images doesn't existcd frontend && npm ci && npm run dev # http://localhost:3000/the_list/The site is served from /the_list/, as on GitHub Pages without the custom domain. npm run build writes the
static site to frontend/dist/; npm run preview serves it under that path. The
frontend’s README has more: its layout, the
Alerts settings for trying sign-in locally, and the screenshot script.
Tests
Backend tests, in a throwaway container with the working tree mounted:
docker compose run --rm --no-deps -v "$PWD/backend:/src" -w /src api \ sh -c "pip install -q -r requirements-dev.txt; python -m pytest -q"Frontend checks, the same ones CI runs. The e2e tests build the site from fixtures and need Playwright’s browser
once (npx playwright install chromium):
cd frontend && npm test && npm run typecheck && npm run lint && npm run e2eWithout Docker
cd backendpython -m venv .venvsource .venv/bin/activatepip install -r requirements-dev.txtcp .env.example .env# edit .env: see Configuration (docs/guide/configuration.md)It needs Python 3.12. Run the tests:
python -m pytestStart the API server (creates tables automatically on first boot):
uvicorn app.main:app --reloadGraphQL playground: http://localhost:8000/graphql. A full ingest also needs Ollama running locally with
nomic-embed-text and tev1:0.8b pulled.
Database migrations
The API creates missing tables on startup, but new columns need an Alembic migration. Alembic uses the
app’s DATABASE_URL.
docker compose exec api alembic upgrade headA database created by the app itself has no Alembic version yet. Mark it once, depending on which models created it:
-
It already has the latest columns (created by the current code): just record that it’s up to date. Running
upgradehere fails, because the columns already exist.Terminal window docker compose exec api alembic stamp head -
It’s missing newer columns (created by older code): mark it at the first migration, then upgrade.
Terminal window docker compose exec api alembic stamp 5b5092d5ef44docker compose exec api alembic upgrade head
Check with docker compose exec api alembic current: it should print the head revision.