Skip to content

armgit / lyftr

Public Imported from GitHub
0

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.example
index 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.md
index 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 ldflag
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 the
default 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`, shared
by web and mobile. `en.json` is the source and the fallback. The languages the app ships
are listed in `locales/README.md`.
diff --git a/README.md b/README.md
index 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 &amp; 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 in
a 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:
```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/Cawlumm/lyftr/main/docker-compose.yml
@@ -71,45 +69,41 @@ docker compose pull && docker compose up -d
Open `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 was
wrong, 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 Apple
Developer 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.yml
index 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.md
index 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, and
without 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 automatically
diff --git a/site/src/content/docs/configuration.md b/site/src/content/docs/configuration.md
index 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.md
index 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.md
index 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.md
index 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 runs
diff --git a/site/src/content/docs/troubleshooting.md b/site/src/content/docs/troubleshooting.md
index 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.astro
index 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.' },