Skip to content

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.

docs: the phone app guide catches up with the App Store, the watch and Play

Duarte Santoscb0a82d458b8
diff --git a/docs/API.md b/docs/API.md
index e3f3ee04c..2abd26e75 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1,7 +1,7 @@
# HTTP API
-The complete openGym HTTP API — every route of `api/server.js`, with auth,
-request/response schemas and the env-dependent behavior — is documented as a
+The complete openGym HTTP API (every route of `api/server.js`, with auth,
+request/response schemas and the env-dependent behavior) is documented as a
hand-written OpenAPI 3.1 spec:
- **Spec (source of truth):** [`api/openapi.yaml`](../api/openapi.yaml)
diff --git a/docs/APP_STORES.md b/docs/APP_STORES.md
index 8708c89e0..dc61e78cf 100644
--- a/docs/APP_STORES.md
+++ b/docs/APP_STORES.md
@@ -128,6 +128,6 @@ on the phone (Settings → Reset, or uninstall).
## Licensing
The repository's `NOTICE.md` carries an app-store exception to the AGPL (an additional
-permission under AGPL §7, since July 2026). The Contributor License Agreement in preparation
-covers the rest: it lets the project keep publishing and updating the store apps long term,
-contributions included.
+permission under AGPL §7, since July 2026). The [Contributor License Agreement](../CLA.md)
+(live since October 2026) covers the rest: it lets the project keep publishing and updating the
+store apps long term, contributions included.
diff --git a/docs/DATA_IMPORTS.md b/docs/DATA_IMPORTS.md
index cf53ca5a8..81222d682 100644
--- a/docs/DATA_IMPORTS.md
+++ b/docs/DATA_IMPORTS.md
@@ -80,7 +80,7 @@ library.
- **Import backup** restores such a file and *replaces* everything currently in the app.
- **Auto-backup on changes** (phone app only) saves a dated copy to `Documents/openGym` after each
workout or routine edit and keeps the newest 14. Point a sync app at that folder to get them off
- the phone — or, on Android, choose the sync app's own folder under Settings → Data & backup → **Backup folder**.
+ the phone, or, on Android, choose the sync app's own folder under Settings → Data & backup → **Backup folder**.
If you host openGym yourself, backing up the `./data` folder covers every profile at once; see
[backups](SELF_HOSTING.md#6-backups).
diff --git a/docs/MOBILE.md b/docs/MOBILE.md
index c283d4b0c..024caf61a 100644
--- a/docs/MOBILE.md
+++ b/docs/MOBILE.md
@@ -1,11 +1,23 @@
# The phone app (Android and iOS)
-**Just want the app?** Download the APK from the
-[latest release](https://github.com/DuarteSantos8/openGym/releases/latest) and read
+**Just want the app?** See [getting the app](#getting-the-app): the App Store (and the public
+TestFlight beta) on an iPhone, the APK on Android. Then read
[how the phone app works](#how-the-phone-app-works) and
-[connecting it to your server](#connecting-the-app-to-your-own-server). On an iPhone, see
-[what's possible](#iphone--whats-actually-possible). Everything from [Prerequisites](#prerequisites)
-on is for building the app yourself.
+[connecting it to your server](#connecting-the-app-to-your-own-server). Everything from
+[Prerequisites](#prerequisites) on is for building the app yourself.
+
+## Getting the app
+
+| | Where | Updates |
+|---|---|---|
+| **iPhone and iPad** | The App Store. Before it is there, or to test the next version early: the [public TestFlight beta](https://testflight.apple.com/join/RKATb61k) | the App Store or TestFlight |
+| **Apple Watch** | Comes with the iPhone app | with the iPhone app |
+| **Android, APK** | [GitHub release](https://github.com/DuarteSantos8/openGym/releases/latest) or [opengym.ch](https://opengym.ch). From v1.4.2 in two sizes: Standard (animations at 180 px) and HD (360 px, bigger download) | the app itself, each size to its own kind |
+| **Android, Google Play** | Coming: the account has to run a closed test first | Google Play, sharper animations as downloads |
+
+The APK and the Google Play app are signed with the same key, so a phone can move from one to
+the other, or between Standard and HD, without losing its data. How the store builds are made and
+released is in [APP_STORES.md](APP_STORES.md).
## How the phone app works
@@ -14,7 +26,7 @@ openGym ships in two flavors from the same codebase:
| | **Self-hosted** (this repo's default) | **Mobile app** (`VITE_MOBILE=1`) |
|---|---|---|
| Runs | in any browser, against your own server | natively on iPhone / Android (Capacitor shell) |
-| Accounts | passkey sign-in, one profile per person | none — the phone *is* the account |
+| Accounts | passkey sign-in, one profile per person | none, the phone *is* the account |
| Data | synced to your server, readable on desktop | stays on the device (file in the app's private storage) |
| Reminders | Web Push from your server | native local notifications, no server involved |
| Exercise media | served by your server (`exercise-media/`) | packed into the app (`exercise-media/`) |
@@ -22,13 +34,13 @@ openGym ships in two flavors from the same codebase:
The mobile flavor never talks to a backend by default: no sign-in screen, no sync, no
telemetry. State is mirrored from `localStorage` into `opengym-state.json` in the app's
private data directory on every change (iOS is allowed to evict WebView storage under
-pressure — the file mirror is the durable copy and is restored on launch). Backups go out
+pressure; the file mirror is the durable copy and is restored on launch). Backups go out
through the OS share sheet instead of a browser download.
### Connecting the app to your own server
On first launch the app asks how you want to use it. Alongside the fully local mode above,
-you can instead **connect it to a self-hosted openGym server** — your data then lives there,
+you can instead **connect it to a self-hosted openGym server**: your data then lives there,
synced the same way the browser PWA does, instead of only on the phone. This is a mode of the
same app, not a different build or download.
@@ -58,13 +70,13 @@ or Settings → Account → **"Connect to my server"** later) to finish. Notes:
A phone that is used at all never runs out; one left unopened for longer than
`SESSION_DAYS` has to be paired again.
- "Sign out everywhere" (Settings → Account, in the browser) revokes a paired app's access
- too — it's the same signed session token either way, just delivered over a header instead
+ too: it's the same signed session token either way, just delivered over a header instead
of a cookie. The phone has no passkey to sign back in with, so it has to be **paired
again**; nothing on it is lost meanwhile (see below). See `/api/pair/create` and
`/api/pair/redeem` in `api/server.js` for the exchange itself.
- Settings → Account → "Disconnect" first checks that your server has every change. If it has, the
phone drops cleanly back to local mode. If not, it says how many changes are missing and
- offers **Try again**, **Export backup**, or **Disconnect anyway** — which keeps those
+ offers **Try again**, **Export backup**, or **Disconnect anyway**, which keeps those
changes on the phone and adds them back the next time it is paired with the same server
and account.
@@ -80,7 +92,7 @@ If your server sits behind [Cloudflare Access](https://developers.cloudflare.com
action that includes that token.
3. In the application's **CORS settings**, enable **Bypass OPTIONS requests to origin**. The
app runs on its own origin, so every request is preceded by a CORS preflight, and a
- preflight never carries the token — without the bypass, Access refuses it and nothing
+ preflight never carries the token. Without the bypass, Access refuses it and nothing
gets through. The openGym API answers the preflight itself and allows both headers.
4. In the app, before connecting: first-launch screen → **Connection settings** (or the
**Cloudflare Access** button in the Connect sheet), enter your server's address and the two
@@ -102,34 +114,34 @@ status bar says so on every screen, and stays until the condition is gone:
| The line says | What it means | What to do |
|---|---|---|
-| *Offline — your changes are saved on this device…* | No answer at all: no network, the server is down, or it did not answer within 20 s (60 s for an upload). | Nothing — it syncs by itself once the server is reachable. **Try again** checks at once. |
+| *Offline. Your changes are saved on this device…* | No answer at all: no network, the server is down, or it did not answer within 20 s (60 s for an upload). | Nothing, it syncs by itself once the server is reachable. **Try again** checks at once. |
| *Your server answered with an error (HTTP 502)…* | The server (or the proxy in front of it) answered with an error. The code is the one the server sent. | Check the server and its proxy logs; **Try again** once it is back. A 413 means the proxy's upload limit is too small (`client_max_body_size`). |
-| *Your server's address answered with something other than openGym (HTTP 200)…* | Something else answered in the server's place — typically a proxy's sign-in page or a catch-all that serves the web app for `/api/*`. | Let `/api/*` through to the openGym API unchanged, including the `Authorization` header. |
+| *Your server's address answered with something other than openGym (HTTP 200)…* | Something else answered in the server's place, typically a proxy's sign-in page or a catch-all that serves the web app for `/api/*`. | Let `/api/*` through to the openGym API unchanged, including the `Authorization` header. |
| *Your server no longer accepts this phone…* | The server refused the phone's token (401): "sign out everywhere", the account disabled, a `data/secret` that was replaced, a token older than `SESSION_DAYS`, or a proxy with its own login that rejects `Authorization: Bearer`. | **Pair again**: in a signed-in browser open Settings → "Pair the mobile app" and enter the new code. The address is already filled in. |
| *This phone is no longer paired with your server…* | A phone that an earlier version of the app unpaired by itself after its token was refused. The address is gone. | **Pair again**, typing the address. |
| *On this phone only, not connected to a server* | Local mode, chosen at first launch or after Disconnect. Said quietly. | Nothing, or **Connect** to pair with a server. |
Don't want the line? Settings → Look & Home → **Show connection status** turns it off (it is on
by default, and the setting travels with your profile). A phone kept local on purpose then shows
-nothing at all. On a phone with a server, a problem — offline, an error, a refused phone, or
-changes still waiting after a few seconds — puts a small orange dot on the **Home** tab and on
+nothing at all. On a phone with a server, a problem (offline, an error, a refused phone, or
+changes still waiting after a few seconds) puts a small orange dot on the **Home** tab and on
the Settings gear instead; Settings → Account → Server & sync says what it is.
In every one of these states the phone keeps its data and every change you make. Pairing
-again with the **same account** merges what the phone kept with what the server has — new
-workouts from both sides, the later edit of each routine, the newer copy's settings — and
+again with the **same account** merges what the phone kept with what the server has (new
+workouts from both sides, the later edit of each routine, the newer copy's settings), and
nothing needs to be exported first. Pairing with a *different* account keeps the first
account's unsent changes aside on the phone until that account comes back.
Where the phone keeps things, in case you ever need them by hand:
-- `opengym-state.json` in the app's private data directory — the durable copy of everything
+- `opengym-state.json` in the app's private data directory: the durable copy of everything
on the phone, written after every change (not reachable without a rooted phone or `adb`
on a debug build). `opengym-state-owner.json` beside it says which account that copy
belongs to: a paired phone only ever takes the file back for that account.
-- `opengym-stash.json`, same directory — changes kept by "Disconnect anyway" or by another
+- `opengym-stash.json`, same directory: changes kept by "Disconnect anyway" or by another
account pairing, waiting for their server and account.
-- `Documents/openGym/opengym-backup-YYYY-MM-DD.json` — only with Settings → Data & backup → **Auto-backup on
+- `Documents/openGym/opengym-backup-YYYY-MM-DD.json`: only with Settings → Data & backup → **Auto-backup on
changes** switched on: a dated copy after every finished workout or edited routine, in a
folder of its own under the phone's Documents folder, where a file manager or a sync app
(Syncthing, a cloud folder) can reach it without taking the rest of Documents along. One
@@ -138,7 +150,7 @@ Where the phone keeps things, in case you ever need them by hand:
the copies versions before 1.3.9 wrote straight into `Documents/`, stay until you remove
them yourself. Settings → Data & backup → **Import backup** reads any of them back, wherever it is.
On Android, Settings → Data & backup → **Backup folder** (under Auto-backup) picks another folder with the
- system folder picker — a sync app's folder, an SD card — and the copies go there instead,
+ system folder picker (a sync app's folder, an SD card) and the copies go there instead,
pruned to the same 14. The choice belongs to this phone and does not sync. If the folder
stops accepting copies (the permission revoked, the folder deleted), they go to
`Documents/openGym` again and Settings says so until you choose the folder again or tap
@@ -148,7 +160,7 @@ Where the phone keeps things, in case you ever need them by hand:
An exercise you create can carry one photo, GIF or short video, and a link to a video or guide.
The file is prepared on the phone before it is kept anywhere: a photo is re-encoded (at most
-1600 px, WebP or JPEG — the location and camera data a phone writes into a photo do not
+1600 px, WebP or JPEG; the location and camera data a phone writes into a photo do not
survive), a GIF loses its comment and metadata blocks, and an MP4/MOV keeps its picture and
sound while its metadata and any GPS or sensor track are zeroed. The original file name is
never stored.
@@ -165,7 +177,7 @@ never stored.
reached the server yet is owed like an unsynced change: **Disconnect** says so and keeps it.
Big files wait for Wi-Fi unless you tap Settings → Data & backup → **Photos & videos**.
- **Backups:** Android's cloud backup leaves `opengym-media/` out
- (`res/xml/backup_rules.xml`, `res/xml/data_extraction_rules.xml`) — Auto Backup drops an
+ (`res/xml/backup_rules.xml`, `res/xml/data_extraction_rules.xml`): Auto Backup drops an
app's whole backup past 25 MB, and a few videos would take the state file down with them. A
device-to-device transfer keeps it. iOS includes Library in iCloud and computer backups.
- **Permissions:** Android already has the camera. iOS asks for the camera
@@ -184,7 +196,7 @@ on-device store for health data, where other apps (Google Fit, Samsung Health, a
can read them. It is off until the user turns it on, and nothing is asked of Health Connect before
that.
-- **What is written:** each finished workout as an exercise session — its start and end, its name
+- **What is written:** each finished workout as an exercise session: its start and end, its name
as the title, the exercises and sets as "Copy as text" writes them as the notes, and a type
(strength training as soon as one exercise is not cardio; walking, running, stationary bike,
elliptical or stair machine for a cardio-only workout on a catalogue machine; "other" otherwise).
@@ -207,12 +219,12 @@ that.
data, or to remove exactly those records.
- **Where it shows:** Android 14 and later have Health Connect built in. On Android 9–13 it is an
app of its own, and the card offers its store page until it is installed. Below Android 9 (the
- app supports Android 6) Health Connect does not exist and the card is not shown.
-- **The library:** `androidx.health.connect:connect-client` 1.1.0-alpha12, called from Java
- (`HealthConnectPlugin.java`) through `runBlocking` on a worker thread, so the Android project stays
- Java-only. 1.1.0 stable needs compileSdk 36 and AGP 8.9.1, a toolchain bump left for its own
- change. The library asks for minSdk 26; `tools:overrideLibrary` keeps the app at 23 and the plugin
- checks the version before touching it.
+ app supports Android 7) Health Connect does not exist and the card is not shown.
+- **The library:** `androidx.health.connect:connect-client` 1.1.0 (the version is pinned in
+ `android/variables.gradle`), called from Java (`HealthConnectPlugin.java`) through `runBlocking`
+ on a worker thread, so the Android project stays Java-only. The library asks for minSdk 26;
+ `tools:overrideLibrary` keeps the app at 24 (Android 7.0) and the plugin checks the version
+ before touching it.
Worth checking on a real device after changes here: turning it on shows Health Connect's own
permission screen; a finished workout appears in Health Connect within a few seconds; deleting it
@@ -260,8 +272,9 @@ and **Delete**.
Info.plist keys `BAAppGroupID`, `BAHasManagedAssetPacks`, `BAUsesAppleHosting`, and the App
Group `group.ch.opengym.app` on the app and the extension. `scripts/ios/finish-ipa.sh` signs the
extension with its own profile (`EXT_PROFILE`).
-- **Android:** the same interface answers "unavailable" until Play Asset Delivery comes; the
- sideloaded APK only ever has its built-in animations.
+- **Android:** the Google Play build has the same packs as Play asset packs (Play Asset Delivery,
+ on demand), behind the same interface (`AnimationPacksPlugin.java` in the `play` flavour). The
+ sideloaded APK has no packs and answers "unavailable": it only ever has its built-in animations.
App Store Connect, once: the App Group `group.ch.opengym.app`; the bundle id
`ch.opengym.app.AnimationPacksDownloader` (an app extension); the App Groups capability on
@@ -274,11 +287,11 @@ cellular with Wi-Fi only on, it waits; Still only shows stills everywhere a work
## Prerequisites
-- Node 20+
-- **Android:** Android Studio (bundles the SDK). Java 21 for Gradle.
-- **iOS:** a Mac with Xcode 15+ and CocoaPods (`brew install cocoapods`). A free Apple ID
+- Node 22 (the Capacitor 8 CLI needs it)
+- **Android:** Android Studio (bundles the SDK, API 36). Java 21 for Gradle.
+- **iOS:** a Mac with Xcode 26 and CocoaPods (`brew install cocoapods`). A free Apple ID
is enough to run the app on your own iPhone (see below); paid membership is only needed
- for App Store distribution, which openGym doesn't do.
+ to publish it.
## Build & run
@@ -291,8 +304,9 @@ npx cap open android # opens Android Studio → run on emulator or device
npx cap open ios # opens Xcode (Mac only) → set your signing team, then run
```
-`npm run build:mobile` bakes the CDN media base into the bundle and copies the web build
-into both native projects — re-run it after every web-code change before building natively.
+`npm run build:mobile` builds the app, puts the 180 px exercise media from `catalogue/media` next
+to it (`scripts/catalogue/stage-media.mjs`) and copies the result into both native projects. Re-run
+it after every web-code change before building natively.
> **Heads-up:** after `build:mobile`, `frontend/dist` contains the *mobile* bundle.
> Run a plain `npm run build` again before deploying `dist` to a server.
@@ -308,39 +322,20 @@ npx @capacitor/assets generate --iconBackgroundColor '#0c0e12' --splashBackgroun
```
(If the generator won't take the SVG directly, export it to `resources/icon.png` at
-1024×1024 first — any image tool can do it.)
-
-## Distribution — deliberately no app stores
+1024×1024 first; any image tool can do it.)
-openGym's mobile app is not on the Play Store or App Store, and that's a choice: no store
-accounts, no store rules, no yearly fees between you and an open-source app.
+## Distributing your own build
-### Android — sideload the APK
+### Android: sideload the APK
-The official signed APK is in four places, all the same file:
+Android asks you to allow installs from the browser the first time; that's standard for any app
+from outside Google Play. Each APK on the release has its `.sha256` beside it, check it if you got
+the file from anywhere else.
-- **[opengym.ch](https://opengym.ch)** — the download page.
-- **[GitLab's package registry](https://gitlab.com/DuarteSantos8/opengym/-/packages)** — every
- build under `opengym-android/<version>/`, with a `.sha256` beside it. Direct link, no login:
- `https://gitlab.com/api/v4/projects/85678327/packages/generic/opengym-android/<version>/openGym-<version>.apk`
-- **[The GitHub release](https://github.com/DuarteSantos8/openGym/releases)** for that version,
- with the APK and its `.sha256` attached as release assets.
-- **[The GitLab release](https://gitlab.com/DuarteSantos8/opengym/-/releases)** on the mirror,
- where the file is built; it links to the package registry above.
-
-Android asks you to allow installs from the browser the first time — that's standard for any
-app outside the Play Store. Check the `.sha256` if you got the file from anywhere else.
-
-Both come out of CI: the `build:apk` job in [`.gitlab-ci.yml`](../.gitlab-ci.yml) runs
-`npm run build:mobile` and `./gradlew assembleSideloadRelease`, then `zipalign`s and signs the result
-with the release key. The job runs on every push to `main` too, so the newest unreleased
-build is always one click away (signed with the same key, installs over a release):
-`https://gitlab.com/DuarteSantos8/opengym/-/jobs/artifacts/main/browse?job=build:apk`
-— a 30-day job artifact, not a package, and not what the in-app updater offers. The key lives in *protected* CI variables (`ANDROID_KEYSTORE_B64`,
-`ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS`), so it only exists on `main` and on `v*`
-tags — a merge request from a fork can build an APK, but gets an unsigned one and never sees
-the key. On a `v*` tag the signed APK is also pushed to the generic package registry, which is
-what the release links to.
+The release APKs are built and signed on the release machine (`scripts/android/build-release.sh`),
+because the animations inside them are larger than the 180 px the licence allows in a repository
+or a CI run. GitLab CI on the mirror can still build a test APK with the repo's 180 px media
+(`build:apk`, a manual job on `main` and merge requests, never on a tag).
The release APK carries native code for ARM only (`arm64-v8a`, `armeabi-v7a`), which is every
phone; the x86 builds of the barcode scanner's library would add about 12 MB for emulators
@@ -353,7 +348,7 @@ To build and sign your own:
cd frontend && npm run build:mobile
cd android && ./gradlew assembleSideloadRelease # → app/build/outputs/apk/sideload/release/app-sideload-release-unsigned.apk
-# one-time: create a keystore. KEEP IT — updates must be signed with the same key,
+# one-time: create a keystore. KEEP IT: updates must be signed with the same key,
# or Android refuses to install the new version over the old one.
keytool -genkeypair -keystore my.keystore -alias opengym -keyalg RSA -validity 10950
@@ -362,43 +357,32 @@ zipalign -f -p 4 app-sideload-release-unsigned.apk aligned.apk
apksigner sign --ks my.keystore --ks-key-alias opengym --out openGym.apk aligned.apk
```
-### iPhone — what's actually possible
+### iPhone: build it yourself
-> The App Store and Google Play builds, and how a release gets there: [APP_STORES.md](APP_STORES.md).
+The App Store app is the easy way. If you want your own build, for example of a fork:
-Apple does not allow installing apps outside the App Store, so there is no `.ipa` download
-that would simply install. Your free options:
-
-- **Self-host + PWA** (recommended): open your instance in Safari → Share → *Add to Home
- Screen*. Full-screen app, no expiry, plus sync and passkeys.
- **Xcode free signing:** open `ios/` in Xcode with a free Apple ID as the team and run it
onto your own iPhone. Apple expires the signature after 7 days; re-run from Xcode to renew.
-- **AltStore:** automates that 7-day re-signing over Wi-Fi via a Mac companion app.
-
-There is a `build:ios` job in [`.gitlab-ci.yml`](../.gitlab-ci.yml) for exactly that path: the
-same mobile bundle, `xcodebuild archive` without a signing identity, and an *unsigned* `.ipa`
-(plus `.sha256`) as job artifact — on a tag also under `opengym-ios/<version>/` in the package
-registry — for AltStore/Sideloadly users to sign with their own Apple ID. It needs a Mac: Xcode
-does not run on the Linux project runner, and gitlab.com's hosted macOS runners are not on the
-free tier. To switch it on, register a Mac as a project runner (shell executor; Xcode, CocoaPods
-and Node installed; give it a tag such as `macos`) and set the CI/CD variable `IOS_RUNNER_TAG`
-to that tag — the job then appears in every `main` and tag pipeline. Until that variable exists
-the job is not part of any pipeline, and it has not run yet, so expect a first round of fixes.
-A signed build (TestFlight, App Store) would additionally need an Apple Developer Program
-membership, the distribution certificate and profile as protected file variables, and an
-`-exportArchive` step — none of that is set up.
+- **AltStore / Sideloadly:** automate that 7-day re-signing.
+- **Self-host + PWA:** open your instance in Safari → Share → *Add to Home Screen*. Full-screen
+ app, no expiry, plus sync and passkeys.
+
+Every pull request that touches the iOS shell is compiled on a Mac by the `iOS` GitHub workflow
+(`.github/workflows/ios.yml`), which also starts it in the simulator. Its unsigned IPA has no
+web assets; `scripts/ios/finish-ipa.sh` adds them and signs it on the release machine.
### Release notes for maintainers
-- Bump `versionName`/`versionCode` in `android/app/build.gradle` per release; keep them in
- step with `frontend/package.json`. `versionCode` must strictly increase or updates won't
- install over an existing APK. The APK is *named* from `frontend/package.json` (the CI job
- reads `version` out of it), so the two drifting apart shows up as a misnamed file.
-- Tagging `vX.Y.Z` is what ships everything: images, APK, release notes. Don't push a version
- tag you don't mean to release — `v*` tags are protected for that reason.
+- Bump `versionName`/`versionCode` in `android/app/build.gradle` per release, and
+ `MARKETING_VERSION`/`CURRENT_PROJECT_VERSION` in the iOS project; keep them in step with
+ `frontend/package.json`. `versionCode` must strictly increase or updates won't install over an
+ existing APK. `scripts/android/build-release.sh` refuses to build when `package.json` and
+ `build.gradle` disagree. The full release list is in [APP_STORES.md](APP_STORES.md).
+- Don't push a version tag you don't mean to release: the published release is what builds the
+ images (`docker-publish.yml`).
- **License:** openGym is AGPL-3.0, which by itself sits badly with app-store terms of
service. `NOTICE.md` carries an app-store exception (an additional permission under
- AGPL §7) granted by the copyright holder — relevant only if store distribution ever happens.
+ AGPL §7) granted by the copyright holder, and the [CLA](../CLA.md) covers contributions.
- The app requests notification permission when the workout-day reminder is switched on,
and again at the first rest if it is still unanswered. On Android it declares
`SCHEDULE_EXACT_ALARM` so the reminder fires to the minute where the user allows exact
diff --git a/docs/README.md b/docs/README.md
index 1f6364948..03f623980 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,7 +8,7 @@ Pick the part that matches what you're doing. If you just have a question, try t
| Guide | Read it when |
|---|---|
| [FAQ](FAQ.md) | You have a quick question: iPhone, cost, where your data goes, AI, the exercise media |
-| [Phone app](MOBILE.md) | You want the Android APK or the iPhone options, or to connect the app to your own server |
+| [Phone app](MOBILE.md) | You want the iPhone app, the Apple Watch or the Android APK, or to connect the app to your own server |
| [Importing data](DATA_IMPORTS.md) | You're coming from FitNotes, Strong, Hevy or Apple Health, or sharing a plan with someone |
| [AI coach](AI_COACH.md) | Your instance has the coach switched on and you want to know what it sees and can change |
@@ -24,7 +24,7 @@ to install.
| [Kubernetes](SELF_HOSTING_KUBERNETES.md) | You run a cluster instead of Docker Compose |
| [AI coach](AI_COACH.md) | You're deciding whether to turn the coach on, and with which provider |
| [MCP server](../mcp/README.md) | You want Claude Desktop, Cursor or another AI client to read your training history |
-| [NixOS](NIX.md) | You run NixOS and want openGym native — flake packages and a NixOS module, no Docker |
+| [NixOS](NIX.md) | You run NixOS and want openGym native: flake packages and a NixOS module, no Docker |
| [Security](../SECURITY.md) | You host it for other people, or want to report a vulnerability |
All settings live in `.env`; [`.env.example`](../.env.example) explains each one, and the
@@ -35,7 +35,10 @@ All settings live in `.env`; [`.env.example`](../.env.example) explains each one
| Guide | Read it when |
|---|---|
| [Contributing](../CONTRIBUTING.md) | Before your first pull request: setup, guidelines, what CI checks |
-| [CLAUDE.md](../CLAUDE.md) | You want the architecture in one page (written for Claude Code, useful for people too) |
+| [Architecture](ARCHITECTURE.md) | You want the map: how the app, server, phones and watch fit together, with diagrams |
+| [App stores and releases](APP_STORES.md) | You're shipping a release: the APK, Google Play and the App Store |
+| [scripts/](../scripts/README.md) | You want to know which build script does what |
+| [CLAUDE.md](../CLAUDE.md) | The same project context in the form Claude Code sessions start from |
| [HTTP API](API.md) | You're touching routes; the OpenAPI spec is the source of truth |
| [Roadmap](../ROADMAP.md) | You want to know what's planned and where your idea fits |
| [Changelog](../CHANGELOG.md) | You want to know what changed in a release |
@@ -47,6 +50,7 @@ Design notes for specific features, kept next to the code they describe:
| [Set types](dev/SET_TYPES.md) | Drop sets and rest-pause: the set-row model and how totals are counted |
| [Workout views](dev/LIST_VIEW.md) | The cards, list and compact layouts of the workout screen |
| [Combine routines](dev/COMBINE_ROUTINES.md) | Spec for running more than one routine in a session |
+| [Fatigue and sets](dev/FATIGUE_SETS_MODEL.md) | How hard sets feed the fatigue map and its recovery time per muscle |
## Still stuck?
diff --git a/docs/SELF_HOSTING_HTTPS.md b/docs/SELF_HOSTING_HTTPS.md
index e5a068a8f..b6cdf2a83 100644
--- a/docs/SELF_HOSTING_HTTPS.md
+++ b/docs/SELF_HOSTING_HTTPS.md
@@ -87,7 +87,7 @@ Additional info:
1. register with desec.io and choose a name (we take `myhomelab` as example)
1. create a new A record that points to your service, e.g.: `*.myhomelab.dedyn.io` (Wildcard!) - 192.168.0.100 (the ip of your homelab/mini PC/Raspberry Pi running the proxy)
2. A wildcard certificate handles all certificates for that given host. e.g.: `opengym.myhomelab.dedyn.io` and `nextcloud.myhomelab.dedyn.io` can share the same certificates.
- 3. create an API token for the certbot plugin. It only needs to write records inside your domain — leave `Can create domains` and `Can delete domains` **off**; a leaked token should not be able to take your domain apart. Note the token, it is only displayed once.
+ 3. create an API token for the certbot plugin. It only needs to write records inside your domain, so leave `Can create domains` and `Can delete domains` **off**; a leaked token should not be able to take your domain apart. Note the token, it is only displayed once.
2. install certbot on your host
1. most linux distributions provide the packages for this, e.g. debian: `apt install certbot python3-certbot-dns-desec` check the [docs](https://desec.readthedocs.io/en/latest/integrations/lets-encrypt.html)
2. create a config file in `/etc/letsencrypt`: `desec.ini` containing `dns_desec_token = YOUR_TOKEN`, and `chmod 600` it
@@ -102,7 +102,7 @@ Additional info:
-d "*.myhomelab.dedyn.io"
```
4. certbot also installs a systemd timer that renews the certificate automatically. Caddy only re-reads the files when told to, so add a deploy hook once: `certbot renew --deploy-hook "systemctl reload caddy"` (or drop that line into `/etc/letsencrypt/renewal-hooks/deploy/`).
- 5. certbot writes `privkey.pem` readable by root only, while caddy runs as its own user. Either `chgrp caddy /etc/letsencrypt/live /etc/letsencrypt/archive && chmod g+rx` those directories (and `g+r` on the key), or copy the files in the deploy hook — otherwise caddy starts, but every TLS handshake fails.
+ 5. certbot writes `privkey.pem` readable by root only, while caddy runs as its own user. Either `chgrp caddy /etc/letsencrypt/live /etc/letsencrypt/archive && chmod g+rx` those directories (and `g+r` on the key), or copy the files in the deploy hook. Otherwise caddy starts, but every TLS handshake fails.
3. install caddy
1. most linux distributions provide the packages for this, e.g. debian: `apt install caddy` check the [docs](https://caddyserver.com/docs/install)
2. create the caddy config, this is an example that should work:
@@ -135,7 +135,7 @@ Additional info:
```
And that's about it. Now you should be able to access your opengym instance from your local network via https with working passkeys.
-Be sure to update the openGym config accordingly (`RP_ID=opengym.myhomelab.dedyn.io`, `ORIGIN=https://opengym.myhomelab.dedyn.io` — see [SELF_HOSTING.md](./SELF_HOSTING.md#2-understand-the-passkey-requirement-important)).
+Be sure to update the openGym config accordingly (`RP_ID=opengym.myhomelab.dedyn.io`, `ORIGIN=https://opengym.myhomelab.dedyn.io`, see [SELF_HOSTING.md](./SELF_HOSTING.md#2-understand-the-passkey-requirement-important)).
**If the name does not resolve on your phone:** many home routers (Fritz!Box, some ISP boxes) have *DNS rebind protection* and silently drop public names that resolve to a private IP. Add `myhomelab.dedyn.io` to the router's rebind exception list, or run your own resolver.
diff --git a/docs/SELF_HOSTING_KUBERNETES.md b/docs/SELF_HOSTING_KUBERNETES.md
index aef6d2044..292899d24 100644
--- a/docs/SELF_HOSTING_KUBERNETES.md
+++ b/docs/SELF_HOSTING_KUBERNETES.md
@@ -4,7 +4,7 @@ Example manifests for a small cluster, contributed from a K3s setup with the Gat
cert-manager. Read [SELF_HOSTING.md](SELF_HOSTING.md) first: the passkey requirement (HTTPS,
`RP_ID`, `ORIGIN`), the settings in `.env.example` and the backup advice apply here unchanged.
-openGym is pretty simple — a frontend and an API backend. The API keeps everything in plain JSON
+openGym is pretty simple: a frontend and an API backend. The API keeps everything in plain JSON
files on a volume. The exercise pictures and animations are part of the web image, so nothing is
downloaded at start-up. There are only a few resources to create:
@@ -16,7 +16,7 @@ downloaded at start-up. There are only a few resources to create:
works as well), plus a cert-manager Certificate for the hostname.
```bash
-git clone https://github.com/DuarteSantos8/openGym # or https://gitlab.com/DuarteSantos8/opengym — same repo
+git clone https://github.com/DuarteSantos8/openGym # or https://gitlab.com/DuarteSantos8/opengym, same repo
cd openGym
# In kubernetes/deployment.yaml, set RP_ID and ORIGIN in spec.template.spec.containers[api].env
# to your hostname, and the hostname in kubernetes/httproute.yaml.
@@ -37,7 +37,7 @@ Notes:
[Envoy Gateway](https://gateway.envoyproxy.io) and [cert-manager](https://cert-manager.io).
- The images are the published `ghcr.io/duartesantos8/opengym-api` and `opengym-web`. The AI
Coach with an API key works on that same API image; the Claude and Codex sign-in providers
- need the `coach` build target, which is not published — build it yourself (see
+ need the `coach` build target, which is not published, so build it yourself (see
[AI_COACH.md](AI_COACH.md)).
- The images are pinned to a release (`1.4.1`), the API and the web image always to the same
one. To update, read the release notes, set the new version on both and apply again; pinning
@@ -52,7 +52,7 @@ Notes:
not the visitor. So the sign-in throttle, which counts attempts per address, acts on the whole
instance at once, and the activity log records the gateway's address. `TRUST_PROXY` is left
off because it would not change that: the API would read the same gateway address from the
- header — and any pod that reaches port 3000 directly could put its own address there. Getting
+ header, and any pod that reaches port 3000 directly could put its own address there. Getting
real visitor addresses needs the gateway to preserve them (for example
`externalTrafficPolicy: Local` on its LoadBalancer Service) and to set a header of its own that
overwrites whatever a client sent; pass that through with `CF_CONNECTING_IP` on the `web`