Pickflix — Build Recipe

Take a bare machine to a running copy of Pickflix — a self-hosted family movie & TV discovery app. It aggregates streaming-available titles from TMDB / OMDb / Trakt, scores them by a composite of RT-critic + RT-audience + Metacritic + Trakt signals, and serves three modes — Family, Mom & Dad, and Smart (personalized, with an optional LLM ensemble) — from a React (Vite) SPA backed by a FastAPI + SQLite service. ~200 tests.

Status: ✅ Verified 2026-07-31 — built from this clean clone on a laptop with a single docker compose up --build. The image builds (Node builds the SPA → Python serves it), the container comes up healthy, and it seeds a bundled demo catalog on first run so the app is fully browsable with ZERO API keys — a real browser at http://localhost:8250 rendered Tonight's Top 10, all four themed shelves, and per-service rows with real posters (loaded from TMDB's public image CDN, which needs no key). The 201-test suite passes bare-metal (Python 3.12, ~39 s, fully offline). Smart mode is off by default and degrades to "algorithmic-only" cleanly. See demo.png for the rendered result. The clean clone lives in clone/. All three tiers are covered — a prebuilt container (a single ~201 MB docker save tarball, verified 2026-08-01), build-from-source, and bare-metal.

Sensitive data — read this. The real app holds a family's profiles, watch history, and Roku devices. None of that is here. A fresh install seeds zero profiles/history/Rokus by construction — the only migration that ever named household members was a no-op on a new database and has been neutralized anyway. The bundled demo catalog is public movie/TV metadata only (titles, ratings, availability — no personal linkage). Real API keys were never copied; only .env.example with placeholders ships.

Attribution: the demo catalog is derived from TMDB (and enriched via OMDb). This product uses the TMDB API but is not endorsed or certified by TMDB. Movie/TV metadata and images are © their respective owners.

What it is

One FastAPI process serves the built SPA at / and a JSON API under /api (port 8250), over a SQLite database managed by Alembic. External data comes from TMDB/OMDb/Trakt (all optional — see below). The Smart-mode LLM ensemble is an optional layer that only affects Smart mode's re-ranking and title suggestions; Family and Mom & Dad modes are 100% LLM-independent.

Prerequisites

New machine? Install the base tools first — see ../SETUP.md. Then, per tier:

Configuration — everything is optional

The app runs with no configuration. cp .env.example .env and you're done; the four data keys and the LLM are all blank by default and the app serves the bundled demo catalog. Fill in keys only to unlock more:

Sign-up links are in clone/.env.example.

Tier 1 — Run the prebuilt container(s) (recommended)

Availability: the prebuilt image bundle is available on request — it is not published or linked anywhere. Ask Kevin for it, or build everything from source via Tier 2/3 below.

Skip the build — load a saved image and start it. Produce the tarball once on a machine that has already built the image (Tier 2):

docker save clone-pickflix -o pickflix-image.tar   # ~201 MB (verified 2026-08-01)

Consume it anywhere — no toolchain, no build:

docker load -i pickflix-image.tar
cd clone
cp .env.example .env
docker compose up -d                        # → http://localhost:8250  (no --build; image is loaded)
curl http://localhost:8250/api/health       # → {"status":"ok","db":"ok",...}

The tarball holds only the single clone-pickflix app image. The opt-in Smart-mode LLM proxy (--profile llm) pulls its own image from ghcr and is not in this tarball — docker save ghcr.io/berriai/litellm:main-latest separately if you want it offline too.

Tier 2 — Build the image from source

cd clone
cp .env.example .env
docker compose up -d --build           # → http://localhost:8250
curl http://localhost:8250/api/health  # → {"status":"ok","db":"ok",...}

Open http://localhost:8250 — the demo catalog renders immediately, no keys. To populate a live, current catalog: put a TMDB_TOKEN (+ optionally OMDb/Trakt) in .env, restart, and click Refresh in Settings (or POST /api/refresh).

Tier 3 — Bare-metal (no Docker)

cd clone
python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e .
cd frontend && npm ci && npm run build && cd ..   # produces frontend/dist (the SPA mount needs it)
cp .env.example .env
mkdir -p data && cp seed/pickflix.seed.db data/pickflix.db   # optional: start from the demo catalog
alembic upgrade head
uvicorn pickflix.main:app --host 0.0.0.0 --port 8250

(Skip the seed copy to start empty. alembic upgrade head on the seeded DB is a no-op — it's stamped at head.)

Optional: Smart-mode LLM

Smart mode works without an LLM (the UI shows "LLM ensemble disabled"). The ensemble needs one OpenAI-compatible endpoint that fronts both model names. Three ways (all in .env.example):

1. Local Ollama — LITELLM_URL=http://host.docker.internal:11434, no key, two local models.
2. Bundled LiteLLM proxy — reproduces the real Claude + Gemini ensemble: bash # set ANTHROPIC_API_KEY + GEMINI_API_KEY + LITELLM_* in .env, then: docker compose --profile llm up -d --build The proxy config is clone/litellm.config.yaml (secret-free — keys come from the environment).
3. OpenRouter — one key fronts both Claude and Gemini over the OpenAI protocol, no proxy, no code change.

(Why a proxy for option 2: Anthropic's native API isn't OpenAI-compatible, so a single-endpoint ensemble needs a gateway/aggregator to serve both models. LiteLLM or OpenRouter both do this.)

Verify

curl http://localhost:8250/api/health
# → {"status":"ok","db":"ok","last_refresh":null,"omdb_today":0}

curl "http://localhost:8250/api/picks?mode=family&kind=movie"
# → JSON with composite[] + themed shelves + service_shelves, all from the seeded catalog

Run the tests (bare-metal, Python 3.12) — fully offline, no keys needed:

pip install -e ".[dev]"
# The API tests drop/recreate schema on DATABASE_URL — point it at a throwaway file:
#   POSIX:       mkdir -p data && DATABASE_URL=sqlite:///data/test.db python -m pytest
#   PowerShell:  $env:DATABASE_URL='sqlite:///data/test.db'; python -m pytest
# → 201 passed

Notes & gotchas

• Zero-key browsing works because a demo catalog is bundled (clone/seed/pickflix.seed.db, ~220 KB, 121 titles). The entrypoint copies it to data/pickflix.db on first run when data/ is empty. Delete data/pickflix.db to re-seed, or add a TMDB_TOKEN and Refresh to build your own live catalog.
• Posters need no key — the frontend loads them from image.tmdb.org, so the seeded catalog renders fully offline of any credential.
• The tests are destructive to DATABASE_URL — they drop_all/create_all on whatever it points at. Always run them against a throwaway DB (above), never your seeded/live one.
• The bundled demo catalog skews toward documentaries (the Mom & Dad discovery pass is documentary-heavy) and the "Trending" shelf is empty (built without a working Trakt key). Both are cosmetic — add keys and Refresh for a fuller, current catalog.
• Alembic and the app share DATABASE_URL — alembic/env.py reads it (falling back to alembic.ini), so one variable drives both. Changing it changes where migrations and the app look.
• Smart mode never crashes on LLM absence — a missing/unreachable endpoint is caught and surfaced as the no-llm state; Smart mode returns its algorithmic picks.

Provenance — data / model (no training, no GPU)

Pickflix trains nothing — there are no datasets and no GPU. The bundled demo catalog was produced by running the app's own refresh pipeline once against public APIs (TMDB discover + OMDb ratings; ~290 TMDB / ~60 OMDb calls, well under free-tier daily caps), then stripped to catalog-only tables. It contains public movie/TV metadata only — no personal data. Attribution: TMDB (see the Status note). The Smart-mode LLM is external and user-supplied; no model weights ship.

What was stripped from the personal version (de-identification + recipe minimalism)

• All real data — the family's SQLite DB, profiles, watch history, and Roku devices → never copied (and never created on a fresh install). The shipped catalog is public metadata only.
• Real secrets — the working-tree .env (live TMDB/OMDb/Trakt keys) → excluded; only .env.example ships. The LiteLLM master key (baked into the old .env.example and several docs) → removed. (These live keys were sitting in the source tree — worth rotating.)
• Personal identifiers in docs/tests — kid names, Roku device names, a Roku IP + serial, and the home server's host IP → scrubbed or replaced with synthetic values; migration 0004's name-based kid seed → neutralized to a pure schema change.
• Home-server deploy scaffolding — docker-compose-fragment.yml, caddy-fragment.txt, the scp/no-git- remote deploy docs, SYSTEM_MAP.md, and the operational docs → dropped. Replaced with a standalone docker-compose.yml, a first-run seed-bootstrap entrypoint, and a clean README.md.
• The LLM's hard LiteLLM coupling — the app now depends only on "an OpenAI-compatible endpoint," off by default; LiteLLM is bundled as an opt-in --profile llm rather than a required service.