- TypeScript 92.6%
- CSS 4.4%
- JavaScript 1.1%
- Python 0.6%
- Nix 0.5%
- Other 0.8%
A device paired by someone holding the old password would otherwise survive the change. Changing the password, or signing out with no token (everywhere), now deletes every device and every open pairing code, with a test. Found by a security review of the phase 6 commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|---|---|---|
| corpus/labels | ||
| ocr | ||
| packages | ||
| scripts | ||
| .dockerignore | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| flake.nix | ||
| openapi.yaml | ||
| package-lock.json | ||
| package.json | ||
| PLAN.md | ||
| README.md | ||
| tsconfig.base.json | ||
burnburn
A self-hosted food, calorie, weight and exercise tracker. One server in
Docker; web, Linux desktop and Android clients; Galaxy Watch data through
Health Connect. PLAN.md is the full plan and build order.
Status: phase 3. The server has first-run setup, auth, generated secrets, the food catalogue, the whole tracking API (diary, own foods, recipes, saved meals, weigh-ins, exercise, Health Connect ingest, goals and targets, day summaries, stats, sync, export/restore), and reading nutrition labels from photos. No UI yet; it waits for the design mockup.
Deploy
docker compose up -d --build
docker compose logs app | grep -i "setup code"
That's the whole deploy. There is no .env file, and none is ever needed:
- Secrets (
JWT_SECRET,ENCRYPTION_KEY) are generated on first start into theburnburn_secretsvolume (mode 600) and reused after that. To supply your own instead, setJWT_SECRET_FILE/ENCRYPTION_KEY_FILE(or the plain variables). A secret under 32 characters, or a known placeholder, stops the server. - The account is created through
POST /api/setup(the web app's first-run screen, once it exists) with the one-time setup code the server prints to its log. The code is deleted once used, and setup closes for good. - Two containers:
app(API and web) andocr(the label reader, internal only; nothing publishes its port). - Optional settings, all with defaults:
BURNBURN_PORT(host port, 3040),TRUST_PROXY(set1behind the Cloudflare tunnel),CATALOG_AUTO_IMPORT(offto import only when asked),OCR_URL(set to an empty string to turn label reading off).
Volumes: burnburn_data holds burnburn.db; burnburn_secrets holds the
generated keys. Back up both (dump the database with sqlite3 .backup, not
a file copy). burnburn_catalog holds the food catalogue; don't back it up.
The food catalogue
About 1.26 million foods from USDA FoodData Central (generic foods, and US
branded products) and Open Food Facts (US products), in catalog.db.
- First start: the server imports everything by itself: about 1.7 GB
of downloads, then about 3 minutes of processing (measured on zeus; 4
minutes in all on a fast connection). Search answers once it finishes.
Progress:
GET /api/catalog/status. - Keeping current: Open Food Facts' daily changes are applied every day. A full rebuild runs monthly, picking up new FDC releases (about twice a year) and products OFF has deleted.
- Barcodes the catalogue lacks are looked up live on Open Food Facts and kept.
- By hand:
POST /api/catalog/importwith{"kind": "full"}or{"kind": "delta"}.
Disk: the catalogue is about 470 MB, plus about 215 MB of FDC zips kept for rebuilds. A full import briefly needs about 2.5 GB more (the 1.5 GB Open Food Facts CSV, deleted afterwards, and the new catalogue built beside the old one).
The web app's first-run screen asks for the code. Until the Docker image serves the web app (phase 5), set up the account with curl:
curl -s localhost:3040/api/setup -H 'Content-Type: application/json' \
-d '{"setupCode":"ABCD-EFGH","username":"matt","password":"a long passphrase"}'
Reading nutrition labels
POST /api/labels/read with a photo of a Nutrition Facts panel as the body.
The ocr container (RapidOCR running PaddleOCR's PP-OCR models, CPU only,
about 5 seconds a label on zeus) reads the text and positions. The parser
in packages/shared/src/label turns that into values and checks each one:
- against its own % Daily Value (both the current and pre-2016 tables);
- calories against 4/4/9 × fat, carbs and protein;
- parts against their whole (sugars ≤ carbs).
Anything that fails a check is marked low for the review screen to point
at. Nothing is saved: the client shows the reading, the person corrects
it, and it's saved through /api/my-foods with the photo's id. Photos
nobody saves a food with are deleted after a day.
To measure the parser against real labels:
node scripts/build-label-corpus.mjs # fetch the corpus photos into .dev/label-corpus
docker build -t burnburn-ocr:local ocr
docker run -d --rm -p 127.0.0.1:8091:8090 --name burnburn-ocr burnburn-ocr:local
npx tsx scripts/eval-labels.ts # OCR is cached; re-score with --cached
The Linux app
A window onto the server's web app, so updating the server updates it too. It signs in with a code instead of a password:
- On the web, open Settings → Devices and choose Add a device. It shows
the server's address and a code like
K7M2-9PQR, good for ten minutes. - Start the app, enter the address and the code. It restarts onto the server.
The code buys the app a device token, kept encrypted by the system keyring
(~/.local/share/burnburn/device-token.enc; the address is in
~/.config/burnburn/server.json). The app's main process spends it on
fifteen-minute access tokens for the page, which never sees the token
itself. Settings → Devices lists every paired device; Disconnect cuts
one off. Plain http:// is accepted only for addresses on the home network
(a private IP or a bare hostname like hermes); anything else must be
https://.
Install it from the flake (packages.<system>.burnburn-desktop, or
overlays.default), or run it from a checkout:
nix develop # node, electron, esbuild
npm run build -w @burnburn/desktop && electron packages/desktop
Under compositors Chromium doesn't recognise (Hyprland, sway), the app asks
libsecret for the keyring; set BURNBURN_PASSWORD_STORE to choose another.
The API
Everything is under /api, described in openapi.yaml. In
short:
| Area | Routes |
|---|---|
| Account | /setup, /auth/* (with /auth/pairing-codes, /auth/pair, /auth/device-session, /auth/devices for paired devices), /profile, /goals, /targets |
| Food | /foods/search (own foods and the catalogue, personal history first), /foods/barcode/:code, /foods/recent, /foods/:id, /my-foods, /favorites, /recipes, /meals |
| Diary | /diary (log, quick add, re-portion, copy), /days/:date |
| Body | /weights, /exercises (with /exercises/activities for the Compendium), /water, /activity, /health-connect/batch |
| Strength | /routines, /workouts (with /workouts/current, /workouts/:id/finish and /workouts/:id/sets) |
| Overview | /stats (per-day figures, averages, weight trend, adaptive TDEE, goal date, streak) |
| Labels | /labels/read (photo in, reading out), /labels/photos/:id |
| Clients | /sync (change feed), /export, /export/diary.csv, /export/restore |
Every synced record takes a client-made id and an optional client
updatedAt, so the phone can work offline: creates are idempotent and the
later edit wins.
Develop
Node 22+.
npm install
npm run dev # server on :3040; data, secrets and catalogue in .dev/
npm run dev -w @burnburn/client # web app on :5173, proxying /api to :3040
npm test # vitest, every workspace
npm run typecheck # tsc over everything, tests included
Layout
| Path | What |
|---|---|
packages/shared |
Types and zod schemas shared by the server and clients |
packages/server |
Express 5 + better-sqlite3/Drizzle API |
packages/client |
The web app: React 19 + Vite, built from the mockups in design/ |
packages/desktop |
The Linux app: an Electron window, pairing, the keyring; package.nix packages it |
packages/server/src/catalog |
Food catalogue: FDC/OFF normalisers, streaming import, search |
packages/server/src/tracking |
Everything tracked: the synced-entity store, diary, foods, recipes, body, summaries, sync, export |
packages/shared/src/calc.ts |
BMR, targets, weight trend, adaptive TDEE, exercise calories: shared so every client agrees |
packages/shared/src/label |
The Nutrition Facts parser, shared so the review screen can re-run it |
ocr/ |
The OCR service (Python, RapidOCR) and its Dockerfile |
corpus/labels |
The label test corpus manifest; photos are fetched, not committed |
openapi.yaml |
The API contract; contract.test.ts keeps it in step with the routes |
Credits
Food data comes from USDA FoodData Central (public domain) and Open Food
Facts (© Open Food Facts contributors, under the Open Database License).
Label reading uses RapidOCR and
PaddleOCR's PP-OCR models (both Apache-2.0). The label test corpus is
Open Food Facts photos (CC BY-SA 3.0, © Open Food Facts contributors).
Activity energy costs come from the 2024 Adult Compendium of Physical
Activities (Herrmann SD, Willis EA, Ainsworth BE, et al. J Sport Health Sci
2024;13(1):6-12, https://pacompendium.com), bundled unchanged in
packages/server/src/exercise/compendium.json and rebuilt with
node scripts/fetch-compendium.mjs.