Fussy Eater — Build Recipe

Take a bare machine to a running copy of Fussy Eater — a self-hosted kids' dinner-planner. A parent adds their children and starts a "session"; the child then swipes through a photo catalog of foods (thumbs up / down, Tinder-style) to discover what they'll actually eat, and the parent sees the results. It's a two-service app — a Node/Express web UI and a Python/Flask food-catalog builder — that share one SQLite DB + image store, with an optional LLM self-expanding catalog.

Status: ✅ Verified 2026-08-01 — built from this clean clone with a single docker compose up --build. Both images build, both services come up healthy, the catalog is seeded on first run (50 real, de-identified foods) into the shared volume, and a browser walked the full parent→child flow key-free: added a child, started a session, and the swipe view rendered real food photos (see demo.png). Both test suites pass — web 5/5 (Jest), catalog 6/6 (pytest) — fully offline. The clean clone lives in clone/. All three tiers are covered — prebuilt tarball (both images, ~462 MB, verified 2026-08-01), build-from-source, and bare-metal.

Sensitive data — read this. This is a kids' app, so it's worth being explicit: no personal or family data is in the source at all. A fresh install creates zero children/sessions/votes (those tables are populated only at runtime, through the UI). The bundled demo catalog is a generic food list — no names, no preferences, no photos of anyone. There is no shipped runtime database. The one rule when reproducing: never copy a running catalog.db (which would hold real kids' names and food ratings) — ship an empty volume, which this recipe does.

What it is

Two services sharing one volume (/app/data → catalog.db + images/): - web (fussy-eater/, Node/Express, port 3000) — the parent + child UI. Owns the DB schema and reads foods from the shared DB. - catalog (fussy-eater-catalog/, Python/Flask, port 5000, internal) — seeds foods + photos into the shared DB on first run, and can optionally self-expand the catalog via an LLM.

The only cross-service call is a one-way web → catalog /expand that fails gracefully. The app runs fully without the catalog service reachable and without any LLM.

Prerequisites

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

Configuration — everything is optional

The app runs with no configuration and no .env — docker compose up is enough. Everything below is opt-in:

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.

Two images ship in one tarball — the web UI (clone-fussy-eater) and the food-catalog builder (clone-fussy-eater-catalog).

# --- produce the tarball once, on a machine that has already built the images ---
docker save clone-fussy-eater clone-fussy-eater-catalog -o fussy-eater-images.tar   # ~462 MB

# --- consume it anywhere (no build needed) ---
docker load -i fussy-eater-images.tar     # loads BOTH images (web + catalog)
cd clone
docker compose up -d                       # → http://localhost:3000  (no --build; images already loaded)
curl http://localhost:3000/health          # → {"status":"ok"}

The whole tarball is ~462 MB (verified 2026-08-01). No keys, no .env — on first boot the catalog seeds the bundled demo catalog into the shared volume, exactly as in Tier 2.

The optional LiteLLM proxy (--profile llm) is not in this tarball — its image (ghcr.io/berriai/litellm:main-latest) is pulled/saved separately, only if you opt in.

Tier 2 — Build the image from source

cd clone
docker compose up -d --build          # → http://localhost:3000

No keys, no .env. On first boot the catalog service copies the bundled demo catalog (foods + images) into the shared volume; the web app is then browsable. Open http://localhost:3000, add a child, and start a session — the child's play screen shows the food cards to swipe.

Tier 3 — Bare-metal (two processes sharing a data dir)

cd clone
# catalog — Python 3.11
cd fussy-eater-catalog && python -m venv .venv && . .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt
DB_PATH=../data/catalog.db IMAGE_DIR=../data/images python app.py          # :5000  (seeds on startup)

# web — Node 20 (separate shell, from clone/)
cd fussy-eater && npm install
DB_PATH=../data/catalog.db IMAGE_DIR=../data/images \
  CATALOG_SERVICE_URL=http://localhost:5000 node server.js                 # :3000

(Both must point DB_PATH/IMAGE_DIR at the same dir — that shared store is how they talk.)

Optional: the LLM self-expanding catalog

The catalog can invent brand-new kid-foods (and generate photos) via an LLM — off by default. It needs one OpenAI-compatible endpoint. Turnkey path = the bundled LiteLLM proxy:

# put OPENAI_API_KEY + LITELLM_* in .env, then:
docker compose --profile llm up -d --build

.env.example documents all three options (bundled LiteLLM / OpenAI-direct / local Ollama). The default docker compose up never starts the proxy.

Verify

curl http://localhost:3000/health                 # → {"status":"ok"}
curl -s http://localhost:5000/status 2>/dev/null || \
  docker compose exec fussy-eater-catalog wget -qO- http://localhost:5000/status
# → {"food_count": 50, "seed_status": "complete", ...}

Then open the UI, add a child, start a session, and swipe — you should see the food catalog with images.

Run the tests (offline, zero keys):

cd fussy-eater && npm install && npm test                   # Jest + Supertest, in-memory DB
cd fussy-eater-catalog && pip install -r requirements.txt && python -m pytest    # Flask, mocked

Notes & gotchas

• Two services, one shared volume. Both mount the same /app/data; the catalog writes foods + images, the web reads them. The compose depends_on: condition: service_healthy makes the web wait until the catalog has seeded, so the UI is never empty on first boot.
• The bundled demo catalog ships ~50 real food photos, de-identified from the author's own running instance — only the generic foods rows + their images were taken; the children/sessions/votes tables were left behind. The app itself also fetches real Wikipedia photos (keyless) when it seeds/expands on a normal network — the fetcher follows redirects and falls back to a Wikipedia search, so descriptive names like "Apple slices with peanut butter" resolve to a real page. To rebuild the catalog from scratch: delete data/, ensure outbound internet, and restart (or POST /expand with an LLM on).
• Catalog port 5000 is internal-only — only the web app (3000) is published; the catalog is reached over the compose network at http://fussy-eater-catalog:5000.
• The play hand-off URL is dynamic — derived from the request host (or PUBLIC_BASE_URL), so the "have your child go to …" link is correct on any machine/LAN.
• The catalog runs Flask's dev server (fine for a personal LAN app; swap for gunicorn for anything public — out of scope for this recipe).

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

Fussy Eater trains nothing — no datasets, no GPU. The bundled demo catalog is ~50 generic kid-foods with real food photos, de-identified from the author's own running instance (the generic foods rows + images only — no personal children/sessions/votes data). The photos were sourced by the app from Wikipedia (keyless) and are food images, not images of any person. The optional self-expanding catalog calls a user-supplied LLM; no model weights ship.

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

• All personal data — never present in source; a fresh install seeds zero children/preferences. The live runtime catalog.db (real kids' names + food votes) is never copied.
• The home-server stack coupling — the two services lived in a ~645-line multi-service compose/apps.yml wired to an external homeserver network, a /mnt/docker-storage host mount, and a shared LiteLLM gateway (with a hardcoded master key). Replaced with a standalone docker-compose.yml (one shared named volume, bridge network) + an opt-in --profile llm.
• A hardcoded internal home-server URL (shape: http://<home-server>:8233/play) in a view → made dynamic (request host / PUBLIC_BASE_URL).
• The hard LiteLLM coupling — the catalog now depends only on "an OpenAI-compatible endpoint," off by default, with the hardcoded model aliases (free-chat/paid-image) made configurable.
• Author infrastructure docs (the home server's facts file, litellm_config.yaml, litellm_callbacks.py, the server-wide compose files, Caddy/homepage config) → not copied.