Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.
JavaScript apple-watchbodyweightdockerfitnessfitness-trackergymhealthiosmcpnodejspasskeysprogressive-web-applicationspwareactself-hostedself-hostingvitewebauthnweightliftingworkout-tracker
Docs: rewrite the README, Discord member count on top, Mermaid diagrams, how openGym is built
Duarte Santos4d8d09cee60c
diff --git a/CLAUDE.md b/CLAUDE.mdindex d7d490153..f60853db5 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -15,13 +15,15 @@ License: AGPL-3.0-or-later.frontend/ React 19 + Vite app (src/views, src/components, src/store, src/lib). Builds to static files.android/ + ios/ are the Capacitor shells for the standalone mobile app (docs/MOBILE.md).api/ backend — server.js (Node, no framework), deps: @simplewebauthn/server, web-push.+ coach/ is the optional AI coach; openapi.yaml documents every route.web/ multi-stage Dockerfile (builds frontend → nginx) + nginx.conf.template (serves app, proxies /api).mcp/ optional MCP server — read-only stdio bridge exposing a user's workouts/1RM/musclebalance to LLM clients (Claude Desktop, Cursor…). Not part of the Docker build; onlyruns when an LLM client spawns it.media/ exercise img/gif, gitignored, fetched at runtime by the `media` compose service.-website/ static marketing site (plain HTML/CSS/JS), deployed separately by .gitlab-ci.yml.-docs/ SELF_HOSTING.md, MOBILE.md.+website/ static project site (plain HTML/CSS/JS), deployed separately.+kubernetes/ example manifests (docs/SELF_HOSTING_KUBERNETES.md).+docs/ user and operator guides: SELF_HOSTING*, MOBILE, AI_COACH, DATA_IMPORTS, API.```## Commands@@ -40,7 +42,8 @@ cd frontend && npm run test:watchnpx vitest run src/lib/progression.test.js # single filenpx vitest run -t "some test name" # single test by name-# MCP server tests+# API and MCP server tests+cd api && npm testcd mcp && npm test# Production build@@ -51,11 +54,13 @@ cd frontend && npm run build:mobile # + cap sync, points media at the CDN dataThere is no linter/formatter configured (no ESLint/Prettier config in the repo) and noTypeScript — match the existing style by hand.-The CI gate is `.gitlab-ci.yml` on GitLab, the canonical remote (see README): it runs the-`frontend/` tests on Node 22 — the same version as `web/Dockerfile` / `api/Dockerfile`-(`node:22-alpine`) — and additionally builds and publishes the Docker images, packages the-signed Android APK, and deploys the demo/docs site. The Gitea and GitHub workflow copies-(`.gitea/workflows/`, `.github/workflows/`) are dormant mirrors; neither host runs them.+GitHub (`github.com/DuarteSantos8/openGym`) is the home of the project; `.github/workflows/mirror.yml`+pushes `main` and `v*` tags to the GitLab mirror. Pull requests are gated by+`.github/workflows/test.yml` on Node 22 — the same version as `web/Dockerfile` / `api/Dockerfile`+(`node:22-alpine`): the frontend, api and MCP suites, the locale checks, and building and booting+both api image targets. GitLab CI on the mirror (`.gitlab-ci.yml`) builds the release artifacts:+the signed Android APK, the multi-arch images and the SBOMs. Never push or merge on GitLab+directly; the mirror is fast-forward only.## Architecturediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 164e25b62..2bc616312 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,20 +1,22 @@# Contributing to openGym-Thanks for taking a look! openGym is intentionally small and dependency-light, and the goal is-to keep it that way — easy to read, easy to self-host.+Thanks for taking a look. openGym is deliberately small and light on dependencies, and the aim is+to keep it that way: easy to read, easy to self-host.## Project layout```frontend/ React + Vite app (src/views, src/components, src/store, src/lib). Builds to static files.- android/ + ios/ are the Capacitor shells for the standalone mobile app (docs/MOBILE.md).-api/ backend — server.js (Node, no framework), one dependency (@simplewebauthn/server).-web/ multi-stage Dockerfile (builds frontend → nginx) + nginx.conf (serves app, proxies /api).-media/ exercise img/gif (gitignored, fetched at runtime).-docs/ self-hosting guide.-mcp/ optional Model Context Protocol server — read-only stdio bridge for LLM apps- (Claude Desktop, Cursor, …) to query a user's workouts/1RM/muscle balance. Not in- the Docker build; only runs when an LLM client spawns it. See mcp/README.md.+ android/ and ios/ are the Capacitor shells for the standalone app (docs/MOBILE.md).+api/ Backend: server.js on plain node:http, two dependencies (@simplewebauthn/server, web-push).+ coach/ is the optional AI coach; openapi.yaml documents every route.+web/ Multi-stage Dockerfile (builds the frontend, serves it with nginx) and the nginx template.+mcp/ Optional read-only MCP server for LLM clients (Claude Desktop, Cursor, ...). Not in the+ Docker build; it only runs when a client spawns it. See mcp/README.md.+website/ The static project site at opengym.duarte-santos.ch.+kubernetes/ Example manifests (docs/SELF_HOSTING_KUBERNETES.md).+docs/ User and operator guides.+media/ Exercise images and GIFs, gitignored and fetched at runtime.```## Running for development@@ -22,75 +24,88 @@ mcp/ optional Model Context Protocol server — read-only stdio bridge for```bashcp .env.example .envdocker compose up -d --build # api + web + media on :8080-# frontend hot reload:-cd frontend && npm install && npm run dev-# training logic (progression rules, 1RM, how a session is read back):-cd frontend && npm test++cd frontend && npm install && npm run dev # hot reload, proxies /api to :3000+cd frontend && npm test # training logic, locales, components+cd api && npm test+cd mcp && npm test```## Guidelines-- **Keep it dependency-light.** The frontend uses React + Router + Zustand and nothing else;- new deps (front or back) are a hard sell. `api/` has two (`@simplewebauthn/server` for passkeys,- `web-push` for notifications) — keep it near that.-- **Match the style.** Small components, clear names, comments only where the "why" isn't obvious.- State lives in the Zustand store (`src/store`); pure helpers in `src/lib`.-- **Don't commit** the exercise media (`media/`) or `data/` — they're gitignored.-- **Test the flow** you touched — click through the affected screens (and the workout flow) in a- browser before opening a merge request.-- **Training logic gets a unit test.** Anything deciding what you lift next, or reading a logged- session back, belongs in a pure helper in `src/lib` with tests beside it (`npm test`). These- rules are easy to get subtly wrong and nearly impossible to verify by clicking — the- progression engine grew two real bugs that only a test pinned down.+- **Keep it dependency-light.** The frontend uses React, React Router and Zustand; `api/` has two+ dependencies. A new dependency on either side is a hard sell.+- **Match the style.** Small components, clear names, comments only where the *why* isn't obvious.+ State lives in the Zustand store (`src/store`), pure helpers in `src/lib`. There is no linter or+ formatter config, so follow the surrounding code.+- **Don't commit** `media/` or `data/`; both are gitignored.+- **Click through what you touched**, including the workout flow, in a browser before opening a+ pull request.+- **Training logic gets a unit test.** Anything that decides what you lift next, or reads a logged+ session back, belongs in a pure helper in `src/lib` with a test beside it. These rules are easy+ to get subtly wrong and nearly impossible to check by clicking; the progression engine has had+ real bugs that only a test caught.+- **New UI strings go into every locale** in `frontend/src/locales/`. English is the source+ language and has no file. `node scripts/check-locales.mjs` (run in CI) flags a key that is+ missing, blank or has lost a `{n}` placeholder. Portuguese (Brazil) inherits from Portuguese+ (Portugal) and has its own guard test.++## Using AI tools++openGym itself is developed with Claude Code (see+[How openGym is built](README.md#how-opengym-is-built)), and [`CLAUDE.md`](CLAUDE.md) holds the+project context for it. You're welcome to use whatever tools you like for a pull request. The bar+is the same either way: you understand the change, it's tested, and you can answer questions about+it in review.## What CI does with your pull request-A pull request runs the three test suites (frontend, MCP, api) through GitHub Actions and-builds and boots both api image targets. The APK and the published images come from the CI-on the GitLab mirror, which builds them from `main` after the merge; if your change needs an-APK to be judged, say so in the PR and a maintainer runs that build.+```mermaid+flowchart LR+ pr["Pull request<br/>on GitHub"] --> actions["GitHub Actions<br/>frontend, api, MCP tests<br/>+ build and boot both api images"]+ actions --> review["Review and merge<br/>into main"]+ review --> mirror["Mirror workflow<br/>pushes to GitLab"]+ mirror --> gitlab["GitLab CI<br/>signed APK, multi-arch images,<br/>SBOMs, release"]+ gitlab --> ghcr["GHCR images<br/>on release"]+```-Merge requests that are still open on the GitLab mirror keep working as before. Every MR runs the three test suites (frontend, MCP, api), with the results and the coverage-of your diff shown in the MR itself, plus a build of the web image and the api image when you-touched their inputs. The frontend job also prints how much your change adds to the gzipped-bundle compared with main. The APK and the published images are manual jobs there (on-`main` both build on every push).+A pull request runs the three test suites and builds and boots both api image targets. The APK and+the published images come from GitLab CI on the mirror, built from `main` after the merge. If your+change needs an APK to be judged, say so in the pull request and a maintainer will run that build.+A first-time contributor's workflows wait for a maintainer to approve them, so "no checks yet"+just means nobody has pressed the button.-One gitlab.com quirk: an MR from a fork runs its pipeline in *your* fork, which usually has-no runners enabled — so it would show "no pipeline" forever. For that reason the project-starts the pipeline on its own runners for you: automatically if you have had an MR merged-here before, otherwise a maintainer presses "Run pipeline" after a first look at the diff-(the MR gets the `ci-approval-needed` label until then). Changes to `.gitlab-ci.yml` or-`scripts/ci/` always go through that manual step.+Merge requests still open on the GitLab mirror are reviewed too and land on `main` here. New work+should come as a GitHub pull request.## Good first issues-- Additional starter plans (upper/lower, full-body, 5×5…)+- More starter plans- More languages for the exercise instructions (the dataset ships several)-- Percentage / training-max programming (5/3/1-style) on top of the progression engine in- `src/lib/progression.js` — the policy interface is already there+- Percentage or training-max programming (5/3/1 style) on top of the progression engine in+ `src/lib/progression.js`; the policy interface is already there- Accessibility passes on the workout and chart screens## Where to ask what| You have | Goes to || --- | --- |-| A quick question, or you'd rather just chat | [The Discord](https://discord.gg/e62jY6fwVb) |-| A question, or self-hosting that won't behave | [An issue labelled `question`](https://github.com/DuarteSantos8/openGym/issues) |-| An idea you're not sure about yet | [An issue labelled `idea`](https://github.com/DuarteSantos8/openGym/issues) |+| A quick question, or you'd rather chat | [Discord](https://discord.gg/e62jY6fwVb) |+| A question, or self-hosting that won't behave | [Discussions → Q&A](https://github.com/DuarteSantos8/openGym/discussions/categories/q-a) |+| An idea you're not sure about yet | [Discussions → Ideas](https://github.com/DuarteSantos8/openGym/discussions/categories/ideas) || A reproducible bug | [Issues](https://github.com/DuarteSantos8/openGym/issues) || A change you've already built | [A pull request](https://github.com/DuarteSantos8/openGym/pulls) |+| A security problem | [Private report](https://github.com/DuarteSantos8/openGym/security/advisories/new), see [SECURITY.md](SECURITY.md) |-Questions and ideas are issues too (one tracker is enough) — just labelled, so nobody-mistakes a question for agreed-on work. An answered question is worth more than the same answer-in a chat log: the next person searching "passkey login fails behind my reverse proxy" finds it.-That is the one thing the Discord can't do, so if an answer there turns out to be worth keeping,-it belongs in an issue afterwards.+An answered question in Discussions is worth more than the same answer in a chat log, because the+next person searching "passkey login fails behind my reverse proxy" finds it. If a Discord answer+turns out to be worth keeping, it belongs in Discussions afterwards.## Reporting bugs-Open an issue with: what you did, what you expected, what happened, and your browser/OS. If it's-about login/passkeys, include your `RP_ID`/`ORIGIN` (not the `data/` contents) — most login-issues are an origin mismatch.+Open an issue with what you did, what you expected, what happened, and your browser and OS. For+login or passkey problems, include your `RP_ID` and `ORIGIN` (not the contents of `data/`); most+login issues are an origin mismatch.-By contributing you agree your work is licensed under the project's [GNU AGPL v3.0](LICENSE).+By contributing you agree that your work is licensed under the project's+[GNU AGPL v3.0](LICENSE).diff --git a/README.md b/README.mdindex 5879fca7e..0cb56b675 100644--- a/README.md+++ b/README.md@@ -2,117 +2,115 @@<img src="assets/banner.png" alt="openGym" width="720">-<br>+**A self-hosted gym and body-weight tracker you actually own.**-**A self-hosted gym & body-weight tracker you actually own.**+Plan your week, run guided workouts, log every set and your body weight —<br>+on your phone, synced across your devices, behind your own passkey login.-Plan your week, run guided workouts, track every set and your body weight over time —-on your phone, synced across devices, behind your own passkey login.-No account on someone else's server, no subscription, no ads. Just `docker compose up`.+[](https://discord.gg/e62jY6fwVb)+[](https://discord.gg/e62jY6fwVb)+[](https://github.com/DuarteSantos8/openGym/stargazers)-<br>--[](LICENSE)------<br>+[](https://github.com/DuarteSantos8/openGym/releases)+[](https://github.com/DuarteSantos8/openGym/actions/workflows/test.yml)[](https://gitlab.com/DuarteSantos8/opengym/-/pipelines)[](https://gitlab.com/DuarteSantos8/opengym/-/pipelines?ref=main)-[](https://github.com/DuarteSantos8/openGym/releases)--[](https://github.com/DuarteSantos8/openGym/stargazers)-[](https://github.com/DuarteSantos8/openGym/issues)-[](https://github.com/DuarteSantos8/openGym/actions/workflows/test.yml)-[](https://github.com/DuarteSantos8/openGym/actions/workflows/mirror.yml)-[](https://discord.gg/e62jY6fwVb)-[](https://buymeacoffee.com/duartesantos)+[](LICENSE)-</div>+[Website](https://opengym.duarte-santos.ch) ·+[Live demo](https://opengym.duarte-santos.ch/demo/) ·+[Android APK](https://github.com/DuarteSantos8/openGym/releases/latest) ·+[Self-hosting guide](docs/SELF_HOSTING.md) ·+[Roadmap](ROADMAP.md) ·+[Changelog](CHANGELOG.md)-<br>+</div>-<div align="center">-<table>+<table align="center"><tr>-<td align="center"><img src="assets/screenshots/home.png" alt="Home" width="230"><br><sub><b>Home</b> — today's workout & weight</sub></td>-<td align="center"><img src="assets/screenshots/workout.png" alt="Workout" width="230"><br><sub><b>Guided workout</b> — animated demos & sets</sub></td>-<td align="center"><img src="assets/screenshots/stats.png" alt="Stats" width="230"><br><sub><b>Stats</b> — heatmap, charts & PRs</sub></td>+<td align="center"><img src="assets/screenshots/home.png" alt="Home screen" width="230"><br><sub><b>Home</b> · today's workout and weight</sub></td>+<td align="center"><img src="assets/screenshots/workout.png" alt="Workout screen" width="230"><br><sub><b>Guided workout</b> · demos and sets</sub></td>+<td align="center"><img src="assets/screenshots/stats.png" alt="Stats screen" width="230"><br><sub><b>Stats</b> · heatmap, charts and PRs</sub></td></tr></table>-</div>--<div align="center">--### [🌐 opengym.duarte-santos.ch](https://opengym.duarte-santos.ch) · [📦 Source on GitHub](https://github.com/DuarteSantos8/openGym) · [🦊 GitLab mirror](https://gitlab.com/DuarteSantos8/opengym)-Screenshots, docs and the APK download live on the site.<br>-<sub>Want to poke at it first? The <a href="https://opengym.duarte-santos.ch/demo/">in-browser-demo</a> is the real app with example data — no account, nothing to install.</sub>+## Why openGym-</div>+Most workout apps keep your data on their servers, push you towards a subscription, or vanish+when the company does. openGym runs on your own box, keeps your data in a folder you control, and+is yours to fork. It still behaves like a modern app: installable on the home screen, passkey+sign-in, works offline, syncs between your phone and your laptop.-## Why+No account on someone else's server, no subscription, no ads, no telemetry. One+`docker compose up` and it's running.-Most workout apps lock your data behind a login on their servers, nag you to upgrade, or-disappear when the startup does. openGym is the opposite: **it runs on your box, your data-stays in a folder you control, and it's yours to fork.** It still feels modern — installable-as a home-screen app, passkey sign-in, offline support, sync across your phone and laptop.+The [in-browser demo](https://opengym.duarte-santos.ch/demo/) is the real app with example data,+if you want to try it before installing anything.## Features-- ⚖️ **Body-weight tracking** — interactive chart with a goal line you set, gains/losses colored by whether they move toward it-- 🏋️ **Weekly plan** — a routine per weekday, over a library of **1,324 exercises** (searchable, with animated demos), browsable **by muscle** on a body map-- ✨ **Four starter plans** — Push/Pull/Legs, Upper/Lower, Full Body, 5×5; loaded as ordinary routines you can edit, and a routine can be copied in one tap-- 🗓️ **Reschedule any day** — sick, missed a session, or fewer gym days this week? Move a workout to another day without touching your weekly plan-- 📅 **Your week starts where you say** — Monday or Sunday, in Settings. The weekly plan, the day strip on Home, the calendar and every "this week" total follow it, so the app reads the way the calendar on your wall does-- 🧭 **A workout screen that gets out of the way** — one ⋯ menu per exercise (note, details, progression, bar weight, warm-up, superset, swap, move, remove), the set number as the set's own menu (drop set, rest-pause burst, remove), and a scrollable **list view** of the whole session with the header pinned. Four switches under Settings → Workout controls bring any of the old button rows back-- 🌈 **Colour-coded RIR / RPE** — one tap logs how hard a set was, with a sentence per level ("one more rep in the tank"); the same colour whether you think in RIR or RPE, a free field for in-between values-- 📖 **History without leaving the workout** — the exercise's last sessions and a progress line, from the ⋯ menu or the exercise details-- ⭐ **Favourite exercises** — star what you use, it sorts first in the picker and the library-- 🖼️ **Your own exercises, with your own picture** — create what the library lacks from a name and a body part, then give it a photo, a GIF or a short video and a link to a video or guide. The file is shrunk and stripped of its location data on the device before it goes anywhere; signed in, it syncs with your profile and still shows offline-- ▶️ **Guided workouts** — it knows what day it is and starts today's session; asks your body weight first, pre-fills your weights from last time, rest timer, PR detection, per-exercise weight tracking. On a rest day it doesn't just say "rest day" — it names when your next session is and what it is-- 🙈 **Animations are your call** — the exercise demos can be full size, small, or hidden entirely during a workout. Hidden collapses the media rather than leaving a gap, for anyone who finds a looping GIF between sets more distracting than useful-- ☀️ **The screen stays awake while you train** — no unlocking the phone and finding your place again between every set. On for as long as a workout is running, released the moment you finish it, and switchable off in Settings-- 🔗 **Supersets** — plan them into a routine or pair two exercises *mid-session* with “make superset with previous/next”, then work through the group back-to-back with a single rest at the end of each round. Unpair at any time; a group of one dissolves itself-- 🔥 **Warm-up sets** — mark the ramp-up rows as warm-ups and they stay out of the numbers that should not see them: no effect on your estimated 1RM, your progression, or the fatigue map, while still being there in the session where you need them. A weight change cascades down the rows that share their phase, not across the divide-- ➖ **Change your mind mid-session** — add an exercise you decided to do, or remove one you didn't, without ending the workout. Removing a member of a superset asks which one-- ⏱️ **Timed exercises** — planks, hangs, wall sits and loaded carries are logged by time, not reps, with a work timer that counts the set itself (separate from the rest timer) and logs the time you actually held. They can carry weight too-- ⏲️ **Rest per exercise** — heavy triples and curls don't want the same break: give any exercise its own rest time and it overrides the global timer for that exercise (a superset rests once, taking the longest). Travels with shared plans-- 🧘 **Planned deloads** — flag a routine as excluded from automatic progression: its sessions open with the routine's own target weights, stay in your history and statistics, and never become the baseline your next regular session progresses from-- 📈 **Progression that follows a rule** — pick one per routine, override it per exercise: linear, **Greyskull LP** (AMRAP top set, double jumps, 10 % resets), double progression through a **visible rep range** (both bounds editable, per-side exercises step in twos), or adding time. Your weights are already right when the session opens, and every target says *why* it's that number. Missed reps never advance the load, stalls trigger a deload, and bodyweight exercises progress in reps instead-- 💪 **Estimated 1RM** — per exercise, from your best eligible set (it names which one), with its own progress curve and a calculator for sets you haven't done. Won't guess above 12 reps-- 🎯 **Effort per set, in your scale** — an optional third column rating how hard a set was, as **RIR** (reps left in the tank) or **RPE** (the same judgement on a 10-point scale). Off by default; each set keeps the scale it was logged with, and nothing else reads the value — your progression and 1RM are unaffected-- 💪 **Bodyweight exercises, logged as bodyweight** — push-ups, pull-ups, dips and 300-odd others arrive knowing they carry no load, so there's no weight column and no working-weight prompt: one stepper, log the reps. Add a dip belt and it reads as an addition, and progression goes back to following the weight. Without one, reps climb — and past a ceiling you set, a set is added instead of a rep, up to the point where the honest advice is load or a harder variation-- ↔️ **Reps per side** — for lunges, single-arm rows and the rest. You log the total, the app shows the split ("8 per side"), and the target steps in twos so it never lands on a number one side can't have-- 🧮 **Structural Balance** — Stats compares your lifts against each other (Poliquin, Thibaudeau and ATG ratios) and names the weakest link-- 🏋️ **Plate math for barbell work** — barbell, EZ, trap bar and Smith machine carry a bar weight (20 kg / 45 lb and friends, or your own per exercise), and the workout screen tells you what goes on each side: *Bar 20 kg · 30 kg per side* — and each set row can show its own plates, worked out from the plates you own. You still log the total, so your history, progression and 1RM keep meaning exactly what they always did-- ✏️ **Edit a saved workout** — fix a weight, add a forgotten set or exercise, or change the duration after the fact, in the same screen you logged it on; progression and records re-read the corrected session. Attach photos and videos to a workout, copy it as text, or save it as a routine-- 📝 **Log a past workout** — forgot your phone, trained on paper, or switched apps? Add a session after the fact from History: date, start time, duration, routine or freestyle, then the normal workout screen — weights, reps, RIR/RPE, timed sets and all. If that day already has a workout you choose: replace it, keep both, or cancel. Backfilled sessions never claim PRs against workouts that came later-- ✏️ **Change when a workout happened** — typed a session in from another app, or logged it on the wrong day? Edit the date and start time of any workout in History. What you lifted is the record and is never touched — the sets, the volume and the notes stay put, and the session keeps the length it had; it just moves to where it belongs. PR badges the new order falsifies are taken back, and only the session you moved can earn one, so imported history never sprouts trophies it never had-- 🎲 **Freestyle sessions** — train without a plan and pick exercises as you go. Each one arrives prefilled from the last time you did it — same sets, same reps and weight by position — so an unplanned session doesn't start by asking you to retype last week-- 🏃 **Cardio** — log time + speed, not just weight × reps-- 📤 **Share a plan** — send someone your routines and week schedule as a small file (no workouts, no weigh-ins), or print it as a clean PDF. Importing merges, so their plan is never overwritten-- 🔧 **Filter by equipment** — narrow the library to what you actually own; the options adapt to what you've picked, so every combination on screen has results behind it-- ✨ **Your own exercises** — a name and a body part is enough; they behave like built-in ones everywhere, with an optional description instead of an animation-- 🟩 **Activity heatmap** — a GitHub-style year view, shaded by time spent training-- 💪 **Muscle map, three ways** — a front-and-back body diagram you can read as **Balance** (where the volume went, over a week, a month or all time — naming the muscles you *haven't* trained), **Fatigue** (what is still recovering, weighted by how close each set was to your maximum, decaying smoothly rather than expiring at a window edge) or **Strength** (how long since you trained each muscle, and behind every one the exercises that built it with their estimated 1RM). It previews what a routine hits while you build it, and shows what you just trained when you finish. Male or female figure, your pick-- 📳 **See the timer end, not just hear it** — an opt-in screen flash when a rest or work timer finishes, for loud gyms and headphones-- 🔔 **Push notifications** — rest-timer alerts even with the app closed, plus an optional reminder on days you have a workout planned but haven't logged one — on the Android app scheduled per calendar date, so a day you already trained or rescheduled stays quiet. Opt in per profile; keys are generated on first run, nothing to configure-- 🔑 **Passkeys, not passwords** — Face ID / Touch ID / fingerprint login; each profile keeps its own data, synced across devices. Add as many passkeys as you have devices, or a new device with a one-time code or QR. An instance can also switch on password sign-in (off by default), by name or e-mail. Sign-ins last 90 days by default (configurable), and “sign out everywhere” in Settings ends every session on every device at once-- 🔄 **Always says where your data is** — a line appears whenever the app is not connected to its server, Settings → Server & sync shows the host, the last sync and anything still waiting, and nothing that has not reached the server is thrown away on disconnect or sign-out-- 🛠️ **Admin dashboard** (optional) — for whoever runs the instance: who's training right now, per-user history, disable accounts, invite-only signup, and an **activity log** of sign-ins, failed attempts and admin actions. Off by default, so a fresh instance stays open with no admin-- 🎨 **Designed, not assembled** — light/dark themes and 8 accent colors saved to your profile, over a hand-drawn icon set instead of emoji, so it looks the same on every phone-- 🌍 **17 languages** — full UI translation (EN, DE, ES, FR, IT, PT (Portugal), PT (Brazil), PL, TR, RU, UK, ZH, KO, HI, TH, HU, AR), with Arabic laid out right to left; exercise instructions localized in 12 of them and built-in exercise names translated in seven (PT-BR, HU, DE, ES, RU, IT, FR), all loaded on demand so the app stays fast. A self-hosted instance can set its default language-- 📥 **Bring your history with you** — import from **FitNotes** (Android and iOS), **Strong** and **Hevy** (CSV or directly with a [Hevy Pro API key](https://hevy.com/settings?developer)), or body weight straight out of an **Apple Health** export. Exercise names are matched against the library and anything unrecognised becomes one of your own exercises, so nothing in the file is dropped-- 📦 **Yours to keep** — one-tap JSON export/import, guest mode, **no telemetry**; switching kg ↔ lb offers to convert every stored number-- 🤖 **Ask an AI about your training** (optional) — an [MCP server](mcp/README.md) lets a client like Claude Desktop or Cursor read your history in your own words: *"what did I bench last week?"*. Read-only, spawned locally by the client, nothing leaves your box. Not in the Docker build — if you don't use an AI assistant, it isn't there-- 🧠 **An AI coach that writes your plan** (optional, off by default) — answer a handful of questions and it designs a week of routines; later it reads what you actually logged and proposes changes, each one with the evidence behind it. You approve every change and can undo it. It runs on **your** server under **your** provider account — Anthropic, OpenAI, Gemini or any OpenAI-compatible endpoint (Ollama on your LAN counts) with a pasted API key on the default image, or the Claude Agent SDK / Codex CLI on a separate build. The phone app can use your instance or its own key. See [docs/AI_COACH.md](docs/AI_COACH.md)-- 📱 **Standalone Android app** — the whole tracker as a sideloadable APK: no account, no server, data on the phone, native workout reminders, the rest countdown in a notification that stays on time with the screen off, and an **in-app update check** that downloads the next signed APK and verifies its checksum ([download](https://opengym.duarte-santos.ch))--## Quick start (self-host)+**Planning**++- A routine per weekday over a library of **1,324 exercises** with animated demos, searchable and+ browsable by muscle on a body map. Filter by the equipment you own.+- Four starter plans (Push/Pull/Legs, Upper/Lower, Full Body, 5×5) that load as ordinary,+ editable routines.+- Move a session to another day without touching the weekly plan. The week starts on Monday or+ Sunday, your choice.+- Supersets, warm-up sets, drop sets and rest-pause, timed exercises (planks, hangs, carries),+ cardio by time and speed, rest time per exercise, planned deloads.+- Your own exercises, with your own photo, GIF or short video. Location data is stripped on the+ device before upload.++**Training**++- Guided sessions: today's workout starts itself, weights are pre-filled from last time, a rest+ timer runs between sets, PRs are detected as you go. On a rest day it tells you when the next+ session is.+- A quiet workout screen: one menu per exercise, the set number as the set's own menu, card or+ list view. Switches in Settings bring the old button rows back if you liked them.+- Optional effort column as RIR or RPE, colour-coded, with a plain-language line per level.+- Plate math for barbell, EZ bar, trap bar and Smith machine, worked out from the plates you own.+- Bodyweight exercises know they carry no load: log reps, add a dip belt if you use one.+- Per-side reps for lunges and single-arm work, the screen stays awake while you train, and a+ rest-timer alert can flash the screen for loud gyms.++**Progress**++- Progression rules per routine or per exercise: linear, Greyskull LP, double progression through a+ visible rep range, or adding time. Each target explains why it is that number; missed reps never+ add load, stalls trigger a deload.+- Estimated 1RM per exercise with its own curve, Structural Balance ratios (Poliquin, Thibaudeau,+ ATG), a year-long activity heatmap.+- A muscle map in three modes: where your volume went, what is still recovering, and what has gone+ untrained.+- Body-weight chart against a goal line.+- Edit any saved workout after the fact, log one you did on paper, or move it to the right date.+ Records are re-read from the corrected history.++**Accounts and data**++- Passkeys (Face ID, Touch ID, fingerprint) with per-profile data synced across devices. Password+ sign-in can be switched on per instance; new devices pair with a one-time code or QR.+- Two devices editing at once merge instead of overwriting each other (see [sync](#how-sync-works)).+- Import from FitNotes, Strong, Hevy (CSV or API key) and Apple Health weight exports. Export+ everything as one JSON file whenever you like.+- Share a plan as a small file or print it as a PDF.+- Optional admin dashboard with invite-only signup and an activity log.+- 17 languages, including right-to-left Arabic. Exercise names and instructions are translated+ for most of them.++**Optional extras, off by default**++- An [AI coach](docs/AI_COACH.md) that drafts a week of routines and later suggests changes based on+ what you logged. You approve every change. It runs on your server with your own provider key+ (Anthropic, OpenAI, Gemini or any OpenAI-compatible endpoint, Ollama included).+- An [MCP server](mcp/README.md) so an assistant like Claude Desktop can answer questions about your+ training history. Read-only and local; not part of the Docker build.++The full list of what changed release by release is in the [changelog](CHANGELOG.md).++## Quick startYou need [Docker](https://docs.docker.com/get-docker/) with Compose.@@ -120,193 +118,249 @@ You need [Docker](https://docs.docker.com/get-docker/) with Compose.git clone https://github.com/DuarteSantos8/openGymcd openGymcp .env.example .env-docker compose pull # grab prebuilt images (amd64 + arm64) — skip to build from source instead+docker compose pull # prebuilt images, amd64 + arm64 (skip this to build from source)docker compose up -d```-Open **http://localhost:8080**, tap **Create profile**, and you're in. First launch downloads-the exercise media (~140 MB) once.--> **About that media:** it reaches openGym through-> [hasaneyldrm/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset), which-> redistributes [ExerciseDB v1](https://exercisedb.dev/) — its metadata and instruction text are-> MIT, but the images and animations are third-party content under *neither* that MIT license nor-> openGym's AGPL, and their ownership is currently disputed between Gym visual and ExerciseDB.-> openGym ships none of it: your instance downloads it from upstream. Reusing it yourself,-> commercially or not, means clearing it with the rights holder — see [NOTICE.md](NOTICE.md).-The prebuilt images are published twice, from the same tag: `registry.gitlab.com/duartesantos8/opengym/{api,web}`-(what `docker-compose.yml` pulls) and `ghcr.io/duartesantos8/opengym-{api,web}` on GitHub — swap the-`image:` lines if you prefer GHCR. Prefer building the images yourself instead of pulling from a-registry? Drop the `pull` step and run `docker compose up -d --build` — you don't need Node or-a build step locally either way.--> Want it reachable from your phone over the internet with passkeys? You'll need an HTTPS-> domain — a two-line change in `.env`. See **[docs/SELF_HOSTING.md](docs/SELF_HOSTING.md)**.--## Mobile app (no server at all)--The same codebase also builds a **standalone mobile app** (Capacitor): no account, no sync,-no backend — everything stays on the phone, with native workout-day reminders and share-sheet-backups. Self-hosting gets you multi-device sync and profiles for friends & family; the-mobile app is the install-and-done flavor.--- **Android:** [**download the APK**](https://opengym.duarte-santos.ch) — or straight from- [GitLab's package registry](https://gitlab.com/DuarteSantos8/opengym/-/packages) or the- [GitHub release](https://github.com/DuarteSantos8/openGym/releases/latest), where every- build sits next to its `.sha256` — and sideload it; openGym is deliberately not on the Play- Store. Or build it yourself: **[docs/MOBILE.md](docs/MOBILE.md)**.-- **iPhone:** Apple doesn't allow installing apps outside the App Store, so there is no iOS- download. Self-host and add it to your home screen from Safari (it's a full PWA), or build- the native app onto your own device from Xcode — see **[docs/MOBILE.md](docs/MOBILE.md)**.+Open <http://localhost:8080>, tap **Create profile**, and you're in. The first start downloads+the exercise media (about 140 MB) once.++To reach it from your phone with passkeys you need HTTPS on a domain; that's a two-line change in+`.env`. The [self-hosting guide](docs/SELF_HOSTING.md) walks through Cloudflare Tunnel, Caddy,+Traefik and nginx, and there are separate guides for+[HTTPS on a LAN](docs/SELF_HOSTING_HTTPS.md) and [Kubernetes](docs/SELF_HOSTING_KUBERNETES.md).++> [!NOTE]+> Images are published from the same tag to `registry.gitlab.com/duartesantos8/opengym/{api,web}`+> (what `docker-compose.yml` pulls) and `ghcr.io/duartesantos8/opengym-{api,web}`. Swap the+> `image:` lines if you prefer GHCR, or run `docker compose up -d --build` to build locally. Either+> way you don't need Node on the host.++<details>+<summary><b>Configuration reference</b> (all through <code>.env</code>)</summary>++| Variable | What it does | Default |+|---|---|---|+| `RP_ID` | Hostname passkeys are bound to | `localhost` |+| `ORIGIN` | Full URL the app is served from | `http://localhost:8080` |+| `WEB_PORT` | Host port for the web UI | `8080` |+| `NGINX_PORT` | Port the web container listens on inside the container | `80` |+| `BACKEND` | Name of the API service that `/api` is proxied to | `api` |+| `PORT` | Port the API listens on; the web container proxies to the same value | `3000` |+| `RP_NAME` | Name shown in the passkey prompt | `openGym` |+| `SESSION_DAYS` | How long a sign-in lasts, in days | `90` |+| `ADMIN_UIDS` | User ids that get the admin dashboard, comma-separated | *(none)* |+| `INVITE_ONLY` | Require an invite code to create a profile | *(off)* |+| `ALLOW_GUEST` | Offer "Continue without account"; `0` requires a profile | *(on)* |+| `PASSWORD_LOGIN` | Offer name-and-password sign-in next to passkeys | *(off)* |+| `TRUST_PROXY` | Let the sign-in throttle read the client address from proxy headers | `1` in `docker-compose.yml` |+| `AUDIT_LOG` | Record sign-ins and admin actions; `0` records nothing | *(on)* |+| `AUDIT_MAX` | Events kept in the activity log; `0` for no limit | `5000` |+| `AUDIT_DAYS` | Days kept in the activity log; `0` keeps until `AUDIT_MAX` | `90` |+| `AUDIT_IP` | Record the caller's address: `off`, `net` (network only) or `full` | `off` |+| `VAPID_SUBJECT` | Contact URL sent with push notifications | your `ORIGIN` |+| `API_TARGET` | API image to build: `default`, or `coach` with the Claude Agent SDK and Codex CLI | `default` |+| `COACH_DISABLED` | `1` forces the AI coach off instance-wide | *(unset)* |++Push-notification keys are generated on first run into `./data/vapid.json`. `DATA_DIR` is pinned to+`/data` inside the container and mapped to `./data` on the host; change the volume, not the+variable. The [self-hosting guide](docs/SELF_HOSTING.md) covers every option in detail.++</details>++## Phone app++The same codebase builds a standalone app with Capacitor: no account, no server, everything stays+on the phone, with native reminders and a rest countdown in the notification shade.++- **Android:** download the signed APK from the [latest release](https://github.com/DuarteSantos8/openGym/releases/latest)+ or the [website](https://opengym.duarte-santos.ch). Each build sits next to its `.sha256`, and+ the app checks for updates itself. openGym is deliberately not on the Play Store.+- **iPhone:** Apple doesn't allow installs outside the App Store. Self-host and add the PWA to your+ home screen from Safari, or build the native app onto your own device with Xcode.++Details and build instructions: [docs/MOBILE.md](docs/MOBILE.md).## How it works+```mermaid+flowchart LR+ phone["Phone or laptop<br/>browser or PWA"]++ subgraph host["Your server"]+ direction LR+ media["media<br/>one-shot download"]+ web["web<br/>nginx: serves the app,<br/>proxies /api"]+ api["api<br/>Node + WebAuthn"]+ data[("./data<br/>JSON files")]+ mcp["MCP server<br/>optional, read-only"]+ end++ upstream["Exercise media<br/>upstream dataset"]+ ai["AI provider<br/>optional, your key"]++ phone -- HTTPS --> web+ upstream -. first start .-> media+ media -- shared volume --> web+ web -- /api --> api+ api --> data+ data -.-> mcp+ api -. coach only .-> ai```-┌─────────────┐ ┌──────────────────────────────┐-│ Your phone │──HTTPS─▶│ web (nginx) │-│ / laptop │ │ ├─ serves the built app │-└─────────────┘ │ └─ proxies /api ──────────┐│- └──────────────────────────────┘│- ▼- ┌──────────────────────────┐- │ api (Node + WebAuthn) │- │ └─ ./data (JSON files) │- └──────────────────────────┘++- **`frontend/`** is React 19 and Vite (React Router, Zustand), built to static files inside Docker.+- **`api/`** is plain `node:http` with two dependencies: `@simplewebauthn/server` for passkeys and+ `web-push` for notifications. Everything is stored as JSON under `./data`.+- **`web/`** builds the frontend and serves it with nginx, proxying `/api` so the whole app sits on+ one origin, which passkeys require.++The training logic (progression rules, 1RM, how a logged session is read back) lives in pure+functions under `frontend/src/lib/` with tests beside them. The HTTP API is documented as an+OpenAPI spec in [`api/openapi.yaml`](api/openapi.yaml), browsable at+[opengym.duarte-santos.ch/api.html](https://opengym.duarte-santos.ch/api.html).++### How sync works++Each profile's data is one document with a server revision. A device sends the revision it last+saw along with its changes; if another device wrote in between, the server refuses and returns the+current document so the device can merge and retry.++```mermaid+sequenceDiagram+ participant P as Phone+ participant S as Server+ participant L as Laptop++ P->>S: save (baseRev 7)+ S-->>P: ok, rev 8+ L->>S: save (baseRev 7)+ S-->>L: 409 conflict + current doc (rev 8)+ Note over L: merge local changes<br/>into rev 8+ L->>S: save (baseRev 8)+ S-->>L: ok, rev 9+ P->>S: poll+ S-->>P: rev 9```-- **frontend/** — React + Vite (React Router + Zustand), built to static files **inside Docker**-- **api/** — Node with no framework, two dependencies (`@simplewebauthn/server` for passkeys, `web-push` for notifications), storing everything as plain JSON files under `./data`-- **web/** — a multi-stage image that builds the frontend and serves it with nginx, proxying `/api` to the backend so it's all on **one origin** (passkeys require this)--The full HTTP API is documented as an OpenAPI spec in [`api/openapi.yaml`](api/openapi.yaml) — browsable at [opengym.duarte-santos.ch/api.html](https://opengym.duarte-santos.ch/api.html).--## Your data--Lives in `./data` on your host: `db.json` (profiles + public passkeys), `state-<user>.json`-(each user's plan, workouts, body weight, settings), `audit.log` (the admin activity log — sign-ins-and admin actions, no IP addresses unless you ask for them) and `secret` (the session-cookie key).-**Back up `./data` and you've backed up everything.** Passkey private keys never touch the-server — they stay in your phone's secure hardware / your password manager.--## Configuration--All via `.env` (see `.env.example`):--| Variable | What it is | Default |-|---------------|------------------------------------------------------|-------------------------|-| `RP_ID` | Hostname passkeys are bound to | `localhost` |-| `ORIGIN` | Full URL the app is served from | `http://localhost:8080` |-| `WEB_PORT` | Host port for the web UI | `8080` |-| `NGINX_PORT` | Port the web container listens on, inside the container | `80` |-| `BACKEND` | Name of the API service that `/api` is proxied to — change it if yours isn't called `api` | `api` |-| `PORT` | Port the API listens on; the web container proxies to the same value | `3000` |-| `RP_NAME` | Name shown in the passkey prompt | `openGym` |-| `SESSION_DAYS`| How long a sign-in lasts, in days | `90` |-| `ADMIN_UIDS` | User ids that get the admin dashboard (comma-separated) | *(none)* |-| `INVITE_ONLY` | Require an invite code to create a profile | *(off)* |-| `ALLOW_GUEST` | Offer "Continue without account" — set `0` to require a profile | *(on)* |-| `PASSWORD_LOGIN` | Offer name-and-password sign-in next to passkeys (see `docs/SELF_HOSTING.md`) | *(off)* |-| `TRUST_PROXY` | Let the sign-in throttle read the visitor's address from proxy headers | `1` in `docker-compose.yml`, else *(off)* |-| `AUDIT_LOG` | Record sign-ins and admin actions — set `0` to record nothing | *(on)* |-| `AUDIT_MAX` | Events kept in the activity log; `0` for no limit | `5000` |-| `AUDIT_DAYS` | Days kept in the activity log; `0` to keep until `AUDIT_MAX` | `90` |-| `AUDIT_IP` | Record the caller's address: `off`, `net` (network only) or `full` | `off` |-| `VAPID_SUBJECT` | Contact URL sent with push notifications | your `ORIGIN` |-| `API_TARGET` | Which API image to build: `default` (no AI runtime — API-key providers still work) or `coach` (adds the Claude Agent SDK + Codex CLI) | `default` |-| `COACH_DISABLED` | Set to `1` to force the AI Coach off instance-wide, whatever the admin toggled | *(unset)* |--Push notification keys are generated on first run and saved to `./data/vapid.json` — nothing to set.-`DATA_DIR` is pinned to `/data` by `docker-compose.yml` and mapped to `./data` on the host; change the-host side of that volume, not the variable.+Nothing that hasn't reached the server is discarded on disconnect or sign-out, and the app shows a+banner whenever it's working offline.++### Your data++Everything lives in `./data` on your host:++| File | Contents |+|---|---|+| `db.json` | Profiles and public passkey data |+| `state-<user>.json` | Each user's plan, workouts, body weight and settings |+| `audit.log` | Admin activity log (no IP addresses unless you turn that on) |+| `secret` | Session-cookie signing key |++Back up `./data` and you've backed up everything. Passkey private keys never reach the server; they+stay in your phone's secure hardware or your password manager.++## Documentation++| Guide | What's in it |+|---|---|+| [Self-hosting](docs/SELF_HOSTING.md) | HTTPS, reverse proxies, multiple users, password sign-in, backups, updates |+| [HTTPS on a LAN](docs/SELF_HOSTING_HTTPS.md) | Certificates at home without exposing the server to the internet |+| [Kubernetes](docs/SELF_HOSTING_KUBERNETES.md) | The manifests in `kubernetes/` |+| [Mobile](docs/MOBILE.md) | The Android and iOS apps, connecting them to your server, building them |+| [AI coach](docs/AI_COACH.md) | Providers, what leaves your server, what the model is allowed to change |+| [Data imports](docs/DATA_IMPORTS.md) | FitNotes, Strong, Hevy, Apple Health |+| [HTTP API](docs/API.md) | The OpenAPI spec and how to lint it |+| [MCP server](mcp/README.md) | Connecting Claude Desktop, Cursor and others to your history |+| [Security](SECURITY.md) | Reporting a vulnerability, and the security model |+| [Contributing](CONTRIBUTING.md) | Dev setup, guidelines, what CI checks |## Roadmap-The plan lives in [ROADMAP.md](ROADMAP.md), and the-[GitHub milestones](https://github.com/DuarteSantos8/openGym/milestones) hold the issues. **A release every-two weeks**, each one small and themed: the promised items, editing finished workouts, the session queue,-programmes and phases, the progression engine, cardio — then **v1.4.0, the foundation: storage moves to a-database and search is rebuilt, the one compatibility break** — then accounts (password and OIDC login,-trainer role, MCP write), the iOS app, the Android and health items, and what all of that unlocks-(pictures for custom exercises, catalogue work, skins, social). Ideas and pull requests welcome.--## Tech--React 19 + Vite (React Router, Zustand) · Node (no framework) · nginx · Docker Compose ·-WebAuthn · exercise data from [hasaneyldrm/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)-(MIT metadata and instructions; media © Gym visual — see [License](#license)).-No database server, no cloud dependencies — the frontend builds inside Docker, so self-hosting-stays a one-command `docker compose up`.--The training logic — progression rules, 1RM estimation, how a logged session is read back —-lives in pure functions under `frontend/src/lib/` with tests next to them: `npm test` in-`frontend/`. Vitest is a dev dependency; the app itself ships no runtime dependencies beyond-React, the router and Zustand.--The optional AI Coach (`api/coach/`) is built the same way round: a by-name allowlist decides-what may leave the server, and a closed-list validator decides what may come back — the model-can touch routines and the weekly schedule, nothing else, and every change is applied on the-client only after you approve it. The core of it — `api/coach/core/` — has no Node dependency,-so the phone app runs the same validator the server does. The in-container AI runtimes live in a-separate Docker build target; the API-key providers need none. See [docs/AI_COACH.md](docs/AI_COACH.md).--The same pure helpers power an optional MCP server (`mcp/`) that lets an LLM client like-Claude Desktop read your data over stdio — see [mcp/README.md](mcp/README.md). Opt-in, not-in the Docker build.+A release roughly every two weeks, each small and themed. The full plan is in+[ROADMAP.md](ROADMAP.md), and the issues sit in the+[GitHub milestones](https://github.com/DuarteSantos8/openGym/milestones).++```mermaid+timeline+ title Next releases+ v1.3.10 (Oct 2026) : Session queue and rotation+ v1.3.11 (Nov 2026) : Programmes and phases+ v1.3.12–13 (Nov–Dec 2026) : Progression engine (AMRAP, %1RM, 5/3/1)+ v1.3.14 (Dec 2026) : Cardio, alternatives, groups+ v1.4.0 (Jan 2027) : Database storage (the one compatibility break)+ v1.4.1–3 (Jan–Feb 2027) : Search, OIDC login, trainer role+ v1.4.4–7 (Mar–Apr 2027) : iOS app, Health Connect, catalogue, skins+```## Community-- **[Discord](https://discord.gg/e62jY6fwVb)** — release announcements, self-hosting help and- the back-and-forth that would be a slow issue thread. Quickest way to get an answer.-- **[Issues](https://github.com/DuarteSantos8/openGym/issues)** — bugs, questions, self-hosting- help and ideas. (Issues still open on the GitLab mirror are read too.) Label a question- `question` and an idea `idea`, and it gets treated as one rather than as agreed-on work. Use- an issue over the Discord for anything the next person should be able to find by searching.-- **Login trouble?** Most of it is an `RP_ID`/`ORIGIN` mismatch — check- [docs/SELF_HOSTING.md](docs/SELF_HOSTING.md) before opening an issue.-- **[Pull requests](https://github.com/DuarteSantos8/openGym/pulls)** — see- [CONTRIBUTING.md](CONTRIBUTING.md). Merge requests already open on the GitLab mirror are still- reviewed and land on `main` here; new work, please, as a pull request.--> **GitHub is home; GitLab is a mirror.** `github.com/DuarteSantos8/openGym` was offline from-> 2026-08-19 to 2026-09-10 while the account was suspended, and the project lived on GitLab in the-> meantime. It is back, and [gitlab.com/DuarteSantos8/opengym](https://gitlab.com/DuarteSantos8/opengym)-> is now kept in sync by a GitHub Actions workflow on every push to `main` and every `v*` tag —-> nothing is pushed or merged there by hand. The mirror stays because its CI builds the release-> artefacts: the signed APK, the multi-arch images (GitLab registry, mirrored to GHCR) and the SBOMs.-> (gitea.com/DuarteSantos/openGym is a plain mirror.) In [CHANGELOG.md](CHANGELOG.md), `!NN` is a-> GitLab merge request from those weeks; `#NN` refers to whichever tracker the report came through.--## Contributing--Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues: more starter-plans, exercise-data languages, import from other trackers. **A ⭐ helps more people find it.**--openGym is free and stays free: AGPL, no subscription, no paid tier, nothing held back for-sponsors. If it replaced a paid tracker for you and you want to chip in, there's a coffee button-below (and a badge at the top) — a star, a bug report or a merge request is worth just as much.--<a href="https://buymeacoffee.com/duartesantos" target="_blank">- <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png"- alt="Buy Me A Coffee"- style="height: 60px !important;width: 217px !important;">+- **[Discord](https://discord.gg/e62jY6fwVb)** for release announcements, self-hosting help and+ quick back-and-forth. Usually the fastest way to get an answer.+- **[Discussions](https://github.com/DuarteSantos8/openGym/discussions)** for questions and ideas+ you want the next person to find by searching.+- **[Issues](https://github.com/DuarteSantos8/openGym/issues)** for reproducible bugs and agreed-on+ work. Login trouble is almost always an `RP_ID`/`ORIGIN` mismatch; the+ [self-hosting guide](docs/SELF_HOSTING.md) covers it.+- **[Pull requests](https://github.com/DuarteSantos8/openGym/pulls)** are welcome; start with+ [CONTRIBUTING.md](CONTRIBUTING.md).++<a href="https://github.com/DuarteSantos8/openGym/graphs/contributors">+ <img src="https://contrib.rocks/image?repo=DuarteSantos8/openGym&max=60" alt="Contributors"></a>+### Where the code lives++GitHub is the home of the project. [gitlab.com/DuarteSantos8/opengym](https://gitlab.com/DuarteSantos8/opengym)+is a mirror, updated by a GitHub Actions workflow on every push to `main` and every release tag. It+exists because its CI builds the release artifacts: the signed APK, the multi-arch images and the+SBOMs. Nothing is merged there by hand. In the changelog, `!NN` refers to a GitLab merge request+from the weeks in August and September 2026 when the project lived there.++## How openGym is built++People have asked about this, so plainly: **openGym is developed with+[Claude Code](https://claude.com/claude-code)**, Anthropic's coding agent. A large share of the+code, tests and documentation is drafted in Claude Code sessions, and the repository carries a+[`CLAUDE.md`](CLAUDE.md) with the project context those sessions start from.++What that does and doesn't mean:++- **A person decides and ships.** What goes in, what gets reviewed and merged, and every release+ are the maintainer's call. Changes are tested on a staging instance and on real phones before+ they are tagged.+- **Tests hold the logic in place.** The training logic is covered by unit tests, and pull requests+ run the frontend, API and MCP suites in CI. That is the guard against plausible-looking code+ that is wrong, whoever or whatever wrote it.+- **The app itself doesn't need an LLM.** Nothing in a default install calls an AI service. The AI+ coach and the MCP server are opt-in, and the coach only talks to the provider you configure, with+ your own key.++Community pull requests are written by their authors, with whatever tools they like, and reviewed+the same way.++## Support++openGym is free and stays free: AGPL, no paid tier, nothing held back for sponsors. If it replaced a+paid tracker for you and you'd like to chip in, there's+[Buy Me a Coffee](https://buymeacoffee.com/duartesantos). A star, a bug report or a pull request+helps just as much.++[](https://star-history.com/#DuarteSantos8/openGym&Date)+## License-**openGym's own code** is [GNU AGPL v3.0](LICENSE) — free and open source. You can self-host,-use, modify and share it; if you run a modified version as a network service, you must offer that-version's source under the same license. Nobody can turn openGym into a closed, proprietary-product.--**Third-party content is not, and openGym cannot sublicense it.** The exercise metadata and-instruction text originate from [ExerciseDB v1](https://exercisedb.dev/) and reach openGym through-[hasaneyldrm/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset) under the-**MIT** license. The exercise images and animations are third-party content covered by neither-that license nor the AGPL, and their ownership is **currently unresolved** — the upstream dataset-attributes them to [Gym visual](https://gymvisual.com/) under a non-transferable permission, while-[ExerciseDB/AscendAPI](https://exercisedb.io/faq) claims to be their creator and owner. A-clarification has been requested. openGym does not redistribute them (your instance fetches them-at first run) and does not relicense them. To reuse that media yourself, clear it with the rights-holder first.--Full third-party notices, including the body-diagram geometry: **[NOTICE.md](NOTICE.md)**.+**openGym's own code** is licensed under the [GNU AGPL v3.0](LICENSE). You can self-host, use,+modify and share it; if you run a modified version as a network service, you have to offer that+version's source under the same license.++> [!IMPORTANT]+> **The exercise media is not covered by that license.** Exercise metadata and instruction text come+> from [ExerciseDB v1](https://exercisedb.dev/) through+> [hasaneyldrm/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset) under MIT. The+> images and animations are third-party content under neither MIT nor the AGPL, and their ownership+> is disputed: the dataset attributes them to [Gym visual](https://gymvisual.com/), while+> [ExerciseDB/AscendAPI](https://exercisedb.io/faq) claims to own them. openGym doesn't redistribute+> them (your instance downloads them on first start) and doesn't relicense them. To reuse that+> media, clear it with the rights holder first.++Full third-party notices, including the body-diagram geometry, are in [NOTICE.md](NOTICE.md).diff --git a/ROADMAP.md b/ROADMAP.mdindex 7151d00d6..2d8eb26de 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -77,14 +77,14 @@ QA sweep of every screen. Left over: routine reordering (#142), the Smith-bar "nAll four promises, plus the iOS keyboard, the assisted machines and a QA sweep of every screen —twenty-four reports in total. See the changelog for the full list.-- Reorder routines in Plan; the Start sheet follows that order (#142) ✅-- "No bar" per exercise, so Smith-machine lifts calculate plates and drop sets from 0 (#138) ✅-- Two decimals on weights, as a display toggle (#139) ✅-- Delete a user from the admin dashboard: credentials, state file, subscriptions, Coach data (#107) ✅+- Reorder routines in Plan; the Start sheet follows that order (#142)+- "No bar" per exercise, so Smith-machine lifts calculate plates and drop sets from 0 (#138)+- Two decimals on weights, as a display toggle (#139)+- Delete a user from the admin dashboard: credentials, state file, subscriptions, Coach data (#107)- Custom-exercise muscle order is fixed, not click order; the import fallback classifies "wrist- curl", "row … neutral grip" and Romanian deadlifts correctly (Discord) ✅+ curl", "row … neutral grip" and Romanian deadlifts correctly (Discord)- The small open pull requests: unknown-path redirect (#185), manifest behind an auth proxy (#184),- standard ß (#190) ✅ — the distance mode (#177, #178) moves to a later release+ standard ß (#190); the distance mode (#177, #178) moves to a later release## v1.3.9 — Editing history (released 2026-09-28, two weeks early)@@ -95,12 +95,12 @@ extra passkeys, custom-exercise pictures, the Android rest notification, plate lStructural Balance, Ukrainian and Arabic. Thirty-nine community pull requests. See the changelog.- **Edit a finished workout** — date, start time, duration, sets, weights, exercises; progression- and 1RM history re-read the corrected session (#143, #203, #263, #218) ✅-- Save a logged workout as a routine (#111, #211) ✅ — repeating a past workout from History and+ and 1RM history re-read the corrected session (#143, #203, #263, #218)+- Save a logged workout as a routine (#111, #211); repeating a past workout from History andundo finish (#58, GitLab !130) move to v1.3.10-- Copy a workout as text ✅ — relabelling an "Unknown" exercise after an import moves to v1.3.10-- Auto-backup keeps the newest 14 files (#161, first half) ✅; a "next step" hotkey independent of- focus (#133) ✅; extra passkeys and the device link (PR #95) ✅ — body measurements (PR #82) move+- Copy a workout as text; relabelling an "Unknown" exercise after an import moves to v1.3.10+- Auto-backup keeps the newest 14 files (#161, first half); a "next step" hotkey independent of+ focus (#133); extra passkeys and the device link (PR #95); body measurements (PR #82) moveto v1.3.10## v1.3.10 — Session queue & rotation (2026-10-25)@@ -111,7 +111,7 @@ Next up.whatever the weekday — with an in-app editor and automatic refill (#158, #69; PR #167 and theeditor on top of it; Discord "not forced into a weekly plan")- Swipe between exercise cards during a workout (#113, GitLab !114) — the swipe preview landed in- v1.3.9 (#202) ✅+ v1.3.9 (#202)- Drag-and-drop exercise order that survives touch (#114 — the first version came out again on2026-09-07; a drag handle on computers came in v1.3.9, #277); the Start/Resume button as "next"during a workout (Discord)@@ -145,7 +145,7 @@ Next up.- Cardio: incline and intervals (rounds × work/rest), interval programmes such as C25k, rucking asdistance + pace + load (#132, #169; Discord "incline treadmill", "cardio programs", "rucking")- Exercise alternatives per routine slot (Discord); Replace in the routine editor came in v1.3.9- (#110) ✅+ (#110)- Complexes and interval groups beside supersets (Discord)## v1.4.0 — Foundation: database (2027-01-10)@@ -171,7 +171,7 @@ default so `docker compose up` stays one line, a server database as an option (D## v1.4.2 — Accounts: password & OIDC (2027-02-07)- Optional username + password login next to passkeys (#118; Discord "Basic login", the- password-manager thread) ✅ — shipped early in v1.3.9, behind `PASSWORD_LOGIN`+ password-manager thread) — shipped early in v1.3.9, behind `PASSWORD_LOGIN`- OIDC login for PocketID / Authelia-style setups (#130, #72; GitLab !132 is the candidate)## v1.4.3 — Trainer & MCP write (2027-02-21)@@ -192,9 +192,9 @@ default so `docker compose up` stays one line, a server database as an option (D- Health Connect for weight and sessions (Discord "Use health connect"); Withings and other scales(#127)-- The rest timer as an ongoing notification on the lock screen (#122, PR #296) ✅ in v1.3.9; a+- The rest timer as an ongoing notification on the lock screen (#122, PR #296) (shipped in v1.3.9); ahome-screen widget (#125)-- APK ABI filters (#136) ✅ in v1.3.9, about 12 MB smaller; the auto-backup directory picker (#161,+- APK ABI filters (#136) (shipped in v1.3.9), about 12 MB smaller; the auto-backup directory picker (#161,second half)- Media for the routine's exercises cached on the phone, so a session works with no signal (#123;Discord "Download all videos")@@ -203,13 +203,13 @@ default so `docker compose up` stays one line, a server database as an option (D## v1.4.6 — Exercises & catalogue (2027-04-04)-- Pictures for custom exercises: upload a photo, GIF or video and a link per exercise ✅ in v1.3.9+- Pictures for custom exercises: upload a photo, GIF or video and a link per exercise (shipped in v1.3.9)(#126, #170); picking one from the catalogue and media on built-in exercises (#259) stay here(Discord "custom images/GIFs", "upload videos")- Catalogue: bench as equipment with flat / adjustable, TRX / suspension, lats and the three deltsas their own categories, exercises that should not carry weight, more routine icons (#132, #188;Discord)-- Choose what the "last time" line shows on the logger (#173) ✅ in v1.3.9; one progress line per set number+- Choose what the "last time" line shows on the logger (#173) (shipped in v1.3.9); one progress line per set number(#145); custom heatmap targets per muscle; a shareable image after a workout (Discord)## v1.4.7 — Looks, social, plugins (2027-04-18)@@ -218,7 +218,7 @@ default so `docker compose up` stays one line, a server database as an option (D#134, #135)- Social: friends, progress and plan sharing (PR #180); a plugin surface for integrations (Discord)- Native NixOS module (GitLab !83) and Azure deployment (!35) only if someone maintains them;- Arabic and right-to-left (GitLab !36) ✅ in v1.3.9+ Arabic and right-to-left (GitLab !36) (shipped in v1.3.9)## How things movediff --git a/SECURITY.md b/SECURITY.mdindex 1d74c0ceb..6e8eb907c 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -8,7 +8,7 @@ need — what the app protects you from and what it doesn't.Only the **latest release**. Releases are semver tags (`v1.0.0` → `v1.2.3`, see[CHANGELOG.md](CHANGELOG.md)); there is no LTS or maintenance branch and older tags are never-patched. A fix ships in the next release and in the `latest` images in GitLab's registry.+patched. A fix ships in the next release and in the `latest` images on both registries.Updating a self-hosted instance:@@ -18,22 +18,18 @@ git pull && docker compose pull && docker compose up -d## Reporting a vulnerability-The project lives on GitLab. It has no security-advisory workflow on the free tier, but it does-have **confidential issues**, and that is the private channel: open an issue at-<https://gitlab.com/DuarteSantos8/opengym/-/issues/new> and tick **"This issue is confidential"**-*before* you submit. A confidential issue is readable only by project members — you'll see it,-I'll see it, nobody else will, and it stays that way if it is later closed.+Use GitHub's private vulnerability reporting:+<https://github.com/DuarteSantos8/openGym/security/advisories/new>. The report is visible only to+you and the maintainer, and it becomes the advisory thread where the fix is discussed and, once+released, published.-If you'd rather not put the details in GitLab at all, open a confidential issue saying only-*"I need an address for a security report"* — no details, no repro, no version — and you'll get-one back within a couple of days.+If you can't use GitHub, ask for an e-mail address on the+[Discord](https://discord.gg/e62jY6fwVb) without giving any details, and you'll get one back within+a couple of days.-> The GitHub repo and its private vulnerability reporting are gone with the suspended account;-> `github.com/DuarteSantos8/openGym/security/advisories/new` no longer resolves.--Please don't put a working exploit in a *non-confidential* issue if it can be used against other-people's instances — and not in the Discord either, which is a public room. Everything else (a crash you can only trigger on your own box, a scanner warning)-is fine as a normal issue.+Please don't put a working exploit in a public issue if it can be used against other people's+instances, and not in the Discord either, which is a public room. Everything else (a crash you can+only trigger on your own box, a scanner warning) is fine as a normal issue.Useful in a report: the version or commit, whether you're running the prebuilt images or asource build, your `RP_ID`/`ORIGIN` and what sits in front of the app, steps to reproduce, and@@ -61,7 +57,8 @@ in the thread; there's no objection, and no request to sit on it indefinitely.change a signed-in user's data.- **Shipped deployment config** — `docker-compose.yml`, `web/nginx.conf`, the two Dockerfiles:a default that exposes something a self-hoster wouldn't expect to be exposed.-- **The published images** `registry.gitlab.com/duartesantos8/opengym/api` and `/web`.+- **The published images** `registry.gitlab.com/duartesantos8/opengym/{api,web}` and+ `ghcr.io/duartesantos8/opengym-{api,web}`.## Out of scope@@ -87,7 +84,8 @@ in the thread; there's no objection, and no request to sit on it indefinitely.in the clear. That is the documented trade of running without TLS, not a finding.- Scanner output with no working exploit, and `npm audit` findings in build-timedevDependencies (Vite, Vitest, Capacitor CLI) that never reach a running instance.-- The GitLab Pages demo build — it has no backend at all, everything stays in that browser.+- The demo build on the website and GitHub Pages — it has no backend at all, everything stays in+ that browser.- Third-party content: the exercise image/GIF dataset and the CDN it's fetched from.## Security model