Self-hosted fitness tracker. Log workouts, track nutrition, and monitor progress. Docker deployment, mobile-friendly.
Document the exercise catalog sync (#217)
Carter1698eb9e9769
diff --git a/.env.example b/.env.exampleindex 467371a..f7d4a75 100644--- a/.env.example+++ b/.env.example@@ -11,11 +11,9 @@ REGISTRATION=open# Seeds [email protected], whose password is public. Leave off on a reachable instance.DEMO_MODE=false-# The open-exercise-db instance the exercise catalog is queried from. Lyftr does not-# ship or seed an exercise library: it asks this API as you search, and keeps only the-# rows it has shown. Unset uses the hosted instance; point it at your own to self-host-# the catalog too. Those rows are re-read once a day, at startup and every 24 hours after,-# in every language the catalog offers.+# Where the exercise catalog is downloaded from (open-exercise-db). Lyftr imports it at+# startup and every 24 hours after, and keeps its own copy. Unset uses the hosted instance;+# set it to use a catalog you host.# OEDB_BASE_URL=https://oedb-api-o4dqddih5q-uk.a.run.app# Address the frontend's nginx proxies /api to, over the internal Docker network.diff --git a/CLAUDE.md b/CLAUDE.mdindex a81f63b..65e6758 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -261,6 +261,9 @@ answering 502 must not evict anyone.## Known Constraints- SQLite FK: `workout_exercises` and `program_exercises` reference `exercises(id)` with no cascade. Never DELETE from exercises while user data exists.+ A row oedb stops listing is hidden (`exercises.upstream_missing_at`, hidden from `List` only), never deleted;+ `markUpstreamMissing` is the one place that decides, and it refuses an export under half of what is held+ (`ErrCatalogShrank`) unless an operator confirms with `?confirm_removals=true`.- Go 1.26 required — Dockerfile must use `golang:1.26-alpine`- Build via `backend/build.sh`, which both Dockerfiles invoke — never `go build` by hand.It is the single source of the version ldflagdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex c72422a..856300c 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -19,7 +19,8 @@ go run .# API listens on http://localhost:3000```-On first run the backend seeds the exercise database automatically. The demo account is+On first run the backend downloads the exercise catalog in the background (it needs network), so+the exercise picker can be empty for a moment. The demo account is**not** seeded unless you ask for it — its password is published right below, so thedefault is off everywhere, development included:@@ -112,6 +113,9 @@ git rebase origin/main## Translations+Today you add or fix a language with a pull request. A web tool for translating without Git (like+Weblate) is planned.+UI strings live in one catalog per language in `packages/shared/src/i18n/locales`, sharedby web and mobile. `en.json` is the source and the fallback. The languages the app shipsare listed in `locales/README.md`.diff --git a/README.md b/README.mdindex 1e3617c..9c60754 100644--- a/README.md+++ b/README.md@@ -1,10 +1,10 @@<p align="center">- <img src="docs/banner.png" alt="Lyftr — self-hosted workout tracking" width="100%" />+ <img src="docs/banner.png" alt="Lyftr: self-hosted workout tracking" width="100%" /></p><p align="center"><b>Self-hosted, mobile-first workout & nutrition tracker.</b><br />- Free, open source, and yours to run — own your data.+ Free, open source, and yours to run. Own your data.</p><p align="center">@@ -32,7 +32,7 @@## What is Lyftr?A workout tracker you fully own. Log workouts, build reusable programs, run a guided gym session with-a rest timer, and track nutrition and bodyweight — all self-hosted and lightweight, with your data in+a rest timer, and track nutrition and bodyweight, all self-hosted and lightweight, with your data ina single SQLite file on your server.No subscription. No lock-in. No "your export is a Pro feature."@@ -46,9 +46,7 @@ No subscription. No lock-in. No "your export is a Pro feature."| 📈 **Progress** | Personal records, progression charts, muscle diagrams, dashboard || 🍎 **Nutrition** | Calories, macros, barcode scan, food search || ⚖️ **Weight** | Trend graph, lbs / kg across all data |-| 🔒 **Yours** | Self-hosted — a single SQLite file, all data on your server |--_Planned: PWA · Strong/Hevy CSV import · iOS app._+| 🔒 **Yours** | Self-hosted, a single SQLite file, all data on your server |<p align="center"><img src="docs/screenshots/workouts-mobile.png" width="150" alt="Workouts" />@@ -60,7 +58,7 @@ _Planned: PWA · Strong/Hevy CSV import · iOS app._## Quick start-No clone, no build — just Docker:+No clone, no build, just Docker:```bashcurl -o docker-compose.yml https://raw.githubusercontent.com/Cawlumm/lyftr/main/docker-compose.yml@@ -71,45 +69,41 @@ docker compose pull && docker compose up -dOpen `http://localhost` and create your account.-📖 **Full guide** — configuration, HTTPS, backups, the mobile app, and troubleshooting live in the+📖 **Full guide**: configuration, HTTPS, backups, the mobile app, and troubleshooting live in the**[docs → lyftr-app.pages.dev](https://lyftr-app.pages.dev)**.## Try it-- **Live demo** — [lyftr-demo.fly.dev](https://lyftr-demo.fly.dev) · `[email protected]` / `password123` (resets hourly; that account is demo-only — your own install has no default login)-- **Android** — [download the APK](https://github.com/Cawlumm/lyftr/releases) from the newest release, then point it at your server ([mobile docs](https://lyftr-app.pages.dev/mobile/)). iOS is planned.+- **Live demo**: [lyftr-demo.fly.dev](https://lyftr-demo.fly.dev) · `[email protected]` / `password123` (resets hourly; that account is demo-only, your own install has no default login)+- **Android**: [download the APK](https://github.com/Cawlumm/lyftr/releases) from the newest release, then point it at your server ([mobile docs](https://lyftr-app.pages.dev/mobile/)). iOS is planned.-## Roadmap+## Tech stack-- [x] Workouts, programs, gym mode, rest timer-- [x] Exercise PRs, progression charts, dashboard-- [x] Weight + nutrition tracking-- [x] Docker deploy · Android app · docs site-- [ ] PWA · Strong/Hevy CSV import · iOS app · hosted option+Go · Gin · SQLite, React · TypeScript · Tailwind · Vite (web), React Native · Expo (mobile),+Astro · Starlight (docs), Docker · nginx.-## Tech stack+## Translations-Go · Gin · SQLite — React · TypeScript · Tailwind · Vite (web) — React Native · Expo (mobile) —-Astro · Starlight (docs) — Docker · nginx.+Help translate Lyftr into your language. See [CONTRIBUTING.md](CONTRIBUTING.md#translations) for how.## Contributing-Bug reports, feature requests, and PRs are welcome — open an issue before large changes. Start with+Bug reports, feature requests, translations, and PRs are welcome. Open an issue before large changes. Start with[CONTRIBUTING.md](CONTRIBUTING.md) for setup and conventions, and [docs/TESTING.md](docs/TESTING.md)for how the test suite is organised.-> **Beta** — actively built, expect rough edges and frequent updates. The software equivalent of+> **Beta**: actively built, expect rough edges and frequent updates. The software equivalent of> going to the gym for the first time.## Support-Lyftr is free and open source under the MIT license — run it on your own hardware, no subscription.+Lyftr is free and open source under the MIT license. Run it on your own hardware, no subscription.The most useful things you can do are free: file a reproducible bug report, fix a doc page that waswrong, or tell another self-hoster it exists.If you'd rather help with the running costs, sponsorship covers the demo server (~$4/month) and the-developer accounts Lyftr needs to reach more platforms — the iOS app is blocked on a $99/year Apple+developer accounts Lyftr needs to reach more platforms. The iOS app is blocked on a $99/year AppleDeveloper account, not on the code.[Sponsor on GitHub](https://github.com/sponsors/Cawlumm) · [All the ways to help](https://lyftr-app.pages.dev/support/)diff --git a/docker-compose.yml b/docker-compose.ymlindex d6f6d95..baaecea 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -16,6 +16,7 @@ services:- DB_PATH=/app/data/lyftr.db- REGISTRATION=${REGISTRATION:-open}- DEMO_MODE=${DEMO_MODE:-false}+ - OEDB_BASE_URL=${OEDB_BASE_URL:-}expose:- "3000"healthcheck:diff --git a/fly/SETUP.md b/fly/SETUP.mdindex f018498..6dc0106 100644--- a/fly/SETUP.md+++ b/fly/SETUP.md@@ -42,7 +42,7 @@ The first deploy will:- Seed the demo user (`[email protected]` / `password123`) — this happens because`fly.toml` sets `DEMO_MODE = "true"`. It is off by default everywhere else, andwithout it the demo deploys with no account to log into-- Begin seeding 800+ exercises async (takes ~30s)+- Begin importing the whole exercise catalog (800+ exercises, English and Spanish) from open-exercise-db in the background (under a minute)- `DemoData` goroutine waits for exercises then seeds 8 weeks of workouts,90 days of weight logs, and 7 days of food logs automaticallydiff --git a/site/src/content/docs/configuration.md b/site/src/content/docs/configuration.mdindex 68174e2..e7e2fe4 100644--- a/site/src/content/docs/configuration.md+++ b/site/src/content/docs/configuration.md@@ -15,6 +15,7 @@ All configuration lives in a `.env` file at the project root.| `BACKEND_ORIGIN` | `backend:3000` | Docker **service name**:port the frontend proxies `/api` to — not a host IP. Only change the port, to match a custom backend `PORT`. || `REGISTRATION` | `open` | Who may create an account: `open`, `first-user`, or `closed`. See below. || `DEMO_MODE` | `false` | Seeds the demo account and sample data. Leave off — its password is public. |+| `OEDB_BASE_URL` | hosted instance | The open-exercise-db the exercise catalog is downloaded from. Set it to use a catalog you host. See [Exercise Library](../exercise-library/). |## Locking down registration@@ -219,8 +220,8 @@ connect() failed (111: Connection refused)If you run the backend on a custom `PORT`, change **only** the port (e.g. `backend:3008`).-## Re-syncing exercises+## Refreshing exercises-Go to **Settings → Exercise Library** to see the current exercise count and a seeding progress-indicator. Hit **Re-sync** to pull the latest exercises — it's a safe upsert, so existing workout-data is untouched.+The server refreshes the exercise catalog by itself at startup and every 24 hours. To refresh now,+go to **Settings → Exercise Library** and press **Refresh cached**. It never touches your workout+data. See [Exercise Library](../exercise-library/).diff --git a/site/src/content/docs/exercise-library.md b/site/src/content/docs/exercise-library.mdindex 7c231ee..6c00a5f 100644--- a/site/src/content/docs/exercise-library.md+++ b/site/src/content/docs/exercise-library.md@@ -1,41 +1,54 @@---title: Exercise Library-description: Lyftr auto-seeds 800+ exercises on first startup from free-exercise-db — no API key, no setup.+description: Lyftr keeps its own copy of the exercise catalog and refreshes it daily. No API key, no setup.----Lyftr ships with an **800+ exercise library** that seeds itself automatically. No API key, no manual-import, no setup.+Lyftr comes with an **800+ exercise library** in English and Spanish. There is no API key and+nothing to import. Your server keeps its own copy and keeps it up to date.-## Automatic seeding+## How it stays up to date-On first startup, Lyftr fetches the catalog from-[free-exercise-db](https://github.com/yuhonas/free-exercise-db) in the background:+- On startup, and then every 24 hours, the server downloads the whole catalog from+ open-exercise-db, in every language it offers.+- If that fails, the server tries again by itself: after 1 minute, then 5, then every 30.+- Searching uses the catalog when it can. If it can't be reached, you get your local copy, so+ logging a workout never waits on the network.+- The server needs outbound HTTPS to the catalog. To use a catalog you host yourself, set+ `OEDB_BASE_URL` in your `.env`.-```-[startup] exercises table empty — fetching from free-exercise-db...-[startup] seed: synced 868 exercises-```+## Settings → Exercise Library++This page shows how many exercises your server holds, when it last synced, and whether the last+sync failed (with the time of the next try). **Refresh cached** syncs now.-The seed runs **async**, so the server is available immediately — exercises appear in the UI within-a few seconds. Each exercise includes its muscle groups, equipment, category, and instructions.+## Empty list on a fresh install?-## Re-syncing+If the picker says **The exercise library is still loading**, the server hasn't been able to reach+the catalog yet. It keeps trying. Press **Refresh cached** to try now, or check the logs:-To pull the latest exercises, go to **Settings → Exercise Library**. It shows the current exercise-count and a progress indicator while seeding. Hit **Re-sync** to update.+```bash+docker compose logs backend | grep -i exercises+```-:::note[Your data is safe]-Re-sync is a safe upsert — it updates the catalog without touching your logged workouts, sets, or-history.-:::+See [Troubleshooting](../troubleshooting/) if your network blocks the catalog.-## Empty list?+## When an exercise is removed-If no exercises appear, check the logs and re-sync:+If the catalog stops listing an exercise, it disappears from the picker, but your workouts and+programs keep it exactly as logged. If the catalog lists it again, it comes back. Nothing you+logged is ever deleted.++## If the catalog suddenly shrinks++If the catalog lists less than half of what your server holds, Lyftr assumes the answer is broken,+removes nothing, and **Refresh cached** says so. If the removal is real, confirm it once as the+server operator:```bash-docker compose logs backend | grep -i seed-```+TOKEN=$(curl -s -X POST https://your-server/api/v1/auth/login \+ -H 'Content-Type: application/json' \+ -d '{"email":"[email protected]","password":"..."}' | jq -r .data.token)-See [Troubleshooting](../troubleshooting/) if the seed can't reach GitHub (it needs outbound HTTPS-on first run).+curl -X POST "https://your-server/api/v1/admin/sync-exercises?confirm_removals=true" \+ -H "Authorization: Bearer $TOKEN"+```diff --git a/site/src/content/docs/faq.md b/site/src/content/docs/faq.mdindex 91e143a..b31fe1b 100644--- a/site/src/content/docs/faq.md+++ b/site/src/content/docs/faq.md@@ -26,8 +26,14 @@ that one file.## Do I need an API key or account for the exercise library?-No. Lyftr seeds 800+ exercises from [free-exercise-db](https://github.com/yuhonas/free-exercise-db)-automatically on first startup. No key, no setup.+No. Your server downloads the whole open-exercise-db+catalog (800+ exercises, with Spanish translations) on first startup and refreshes it every day. No+key, no setup. See [Exercise Library](../exercise-library/).++## Which languages does Lyftr support?++English and Spanish, in the app and in the exercise library. More are welcome. To add one, open a+pull request: see [Translations](https://github.com/Cawlumm/lyftr#translations).## Which platforms are supported?diff --git a/site/src/content/docs/self-hosting.md b/site/src/content/docs/self-hosting.mdindex c7526fa..84fad3d 100644--- a/site/src/content/docs/self-hosting.md+++ b/site/src/content/docs/self-hosting.md@@ -40,9 +40,10 @@ step matters.::::::tip[Exercise library]-On first startup Lyftr seeds **800+ exercises** from-[free-exercise-db](https://github.com/yuhonas/free-exercise-db) in the background — no API key, no-setup. They appear in the UI within a few seconds.+On first startup Lyftr downloads the whole **800+ exercise** catalog from+open-exercise-db in the background — no API key, no+setup — and refreshes it every 24 hours. It needs outbound HTTPS to do that. See+[Exercise Library](../exercise-library/).:::## Where it runsdiff --git a/site/src/content/docs/troubleshooting.md b/site/src/content/docs/troubleshooting.mdindex a9375f0..d759e1d 100644--- a/site/src/content/docs/troubleshooting.md+++ b/site/src/content/docs/troubleshooting.md@@ -1,6 +1,6 @@---title: Troubleshooting-description: Fixes for the most common Lyftr self-hosting issues — 502 errors, login, ports, and exercise seeding.+description: Fixes for the most common Lyftr self-hosting issues — 502 errors, login, ports, and the exercise library.---The common issues, and how to fix them.@@ -69,12 +69,14 @@ the phone's camera rather than the browser's.## No exercises show up-They seed in the background on first startup and appear within a few seconds. If the list is empty,-check the logs and use **Settings → Exercise Library → Re-sync**. See-[Exercise Library](../exercise-library/).+The server downloads the exercise catalog in the background on first startup. If the picker says+**The exercise library is still loading**, it hasn't been able to reach the catalog yet. It retries+by itself; **Settings → Exercise Library → Refresh cached** tries now, and shows why it failed.+The server needs outbound HTTPS to the catalog host (`OEDB_BASE_URL`, or the hosted instance by+default). See [Exercise Library](../exercise-library/).```bash-docker compose logs backend | grep -i seed+docker compose logs backend | grep -i exercises```## Still stuck?diff --git a/site/src/pages/index.astro b/site/src/pages/index.astroindex d3fcf33..2d3889a 100644--- a/site/src/pages/index.astro+++ b/site/src/pages/index.astro@@ -37,7 +37,7 @@ const proof = [];const features = [- { t: '800+ exercise library', d: 'Auto-seeded on first startup from free-exercise-db — no API key, no setup.' },+ { t: '800+ exercise library', d: 'Downloaded on first startup from open-exercise-db and refreshed daily — no API key, no setup.' },{ t: 'Program builder', d: 'Reusable workout templates you can start with one tap.' },{ t: 'Guided active workout', d: 'Set-by-set flow so you always know what’s next.' },{ t: 'Gym Mode + rest timer', d: 'Full-screen, one exercise at a time, with a built-in rest timer.' },