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: the real store flow (finish-ipa with every profile, Build Uploads API, Background Assets packs, Play Asset Delivery), TestFlight beta in the README
Duarte Santos8dccae958492
diff --git a/README.md b/README.mdindex 87eeacfa4..769f38b83 100644--- a/README.md+++ b/README.md@@ -24,6 +24,7 @@ on your phone, synced across your devices, behind your own passkey login.[Website](https://opengym.ch) ·[Live demo](https://opengym.ch/demo/) ·[Android APK](https://github.com/DuarteSantos8/openGym/releases/latest) ·+[iPhone beta (TestFlight)](https://testflight.apple.com/join/RKATb61k) ·[Self-hosting guide](docs/SELF_HOSTING.md) ·[Roadmap](ROADMAP.md) ·[Changelog](CHANGELOG.md)@@ -190,9 +191,10 @@ on the phone, with native reminders and a rest countdown in the notification sha- **Android:** download the signed APK from the [latest release](https://github.com/DuarteSantos8/openGym/releases/latest)or the [website](https://opengym.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.+ the app checks for updates itself. A Google Play version is on its way.+- **iPhone and Apple Watch:** the App Store app, with a public+ [TestFlight beta](https://testflight.apple.com/join/RKATb61k) until it is out. Or self-host and+ add the PWA to your home screen from Safari.Details and build instructions: [docs/MOBILE.md](docs/MOBILE.md).diff --git a/docs/APP_STORES.md b/docs/APP_STORES.mdindex 8708c89e0..3f1156b83 100644--- a/docs/APP_STORES.md+++ b/docs/APP_STORES.md@@ -6,7 +6,7 @@ openGym ships to phones three ways, all from the same code and the same version|---|---|---|---|| Android APK | GitHub release, opengym.ch | the app itself (Settings → About) | release machine || Android, Google Play | Play Store | Google Play | release machine |-| iPhone | App Store | the App Store | Mac runner (compile) + release machine (finish, sign) |+| iPhone (+ Apple Watch) | App Store, TestFlight beta | the App Store | Mac runner (compile) + release machine (finish, sign, upload) |The two Android builds are flavours of one Gradle project (`frontend/android/app/build.gradle`):`sideload` keeps the updater (InstallPlugin, `REQUEST_INSTALL_PACKAGES`), `play` leaves both out,@@ -37,9 +37,11 @@ ever sees the repo's 180 px media.## Every release-Bump the version in the usual places, plus the iPhone app's-`MARKETING_VERSION` (= `versionName`) and `CURRENT_PROJECT_VERSION` (= `versionCode`) in-`frontend/ios/App/App.xcodeproj/project.pbxproj`.+Bump the version in the usual places, plus the iPhone app's `MARKETING_VERSION` (= `versionName`)+and `CURRENT_PROJECT_VERSION` in `frontend/ios/App/App.xcodeproj/project.pbxproj`. The iPhone build+number counts on its own (every TestFlight build takes the next one, App Store Connect refuses a+number it has seen), so it runs ahead of the Android `versionCode`. The extensions and the watch+app take both numbers from the app target.### Android@@ -64,16 +66,61 @@ with the release notes from the changelog.### iPhone-1. Push the tag; the `iOS` workflow (`.github/workflows/ios.yml`) builds `ios-unsigned-ipa` for it.- Download that artifact (`gh run download <run> -n ios-unsigned-ipa`).-2. Build the phone bundle with the app's animations, from the same commit:+The IPA carries the app, the asset pack downloader extension (`AnimationPacksDownloader`), the+widget extension (`OpenGymWidgets`: widgets and the Live Activity) and the Apple Watch app with its+own widget. Each is a separate bundle id with its own App Store provisioning profile.++1. **Compile (CI).** The `iOS` workflow (`.github/workflows/ios.yml`, job `device-archive`) runs+ on every push to `main` and `stores` and archives the app for devices, unsigned, without the+ exercise media, and stamps the commit into the zip (`ci-commit.txt`). Download the+ `ios-unsigned-ipa` artifact of the release commit (`gh run download <run> -n ios-unsigned-ipa`).+2. **Phone bundle with the animations**, from the same commit, on the release machine:`cd frontend && VITE_CLIP_EXT=webp APP_MEDIA_DIR=/mnt/backup-hdd/opengym-media/build-appwebp npm run build:mobile`-3. Finish and sign it:- `scripts/ios/finish-ipa.sh App-unsigned.ipa dist.p12 dist.pass openGym_AppStore.mobileprovision`- It refuses an IPA from another commit or a bundle without the animations.-4. Upload: `iTMSTransporter -m upload -assetFile openGym-X.Y.Z.ipa -apiKey <KEY_ID> -apiIssuer <ISSUER_ID>`- (Apple's Transporter for Linux, with an App Store Connect API key in `~/.appstoreconnect/private_keys/`).- The build shows up in TestFlight after Apple's processing; submit it for review from there.+3. **Finish and sign** (`scripts/ios/finish-ipa.sh`, no Mac needed, `rcodesign` signs on Linux):+ ```sh+ EXT_PROFILE=downloader.mobileprovision WIDGETS_PROFILE=widgets.mobileprovision \+ WATCH_PROFILE=watch.mobileprovision WATCH_WIDGET_PROFILE=watch-widget.mobileprovision \+ scripts/ios/finish-ipa.sh App-unsigned.ipa dist.p12 dist.pass openGym_AppStore.mobileprovision+ ```+ It puts the phone bundle into the app, signs every bundle with its own profile's entitlements+ (App Group, HealthKit where the profile and the app ask for it), and refuses an IPA from+ another commit, a version that differs from `frontend/package.json`, a bundle without the+ animations, or an extension in the IPA without its profile.+4. **Upload** through the App Store Connect API (Build Uploads), with an App Store Connect API key+ (a JWT signed with the key, kept next to the signing material, never in the repo). No Mac and+ no Transporter needed:+ 1. `POST /v1/buildUploads` with the version, the build number, platform `IOS` and the app;+ 2. `POST /v1/buildUploadFiles` for the IPA (file name, size, `uti` `com.apple.ipa`): the answer+ lists `uploadOperations` (URL, method, headers, offset, length);+ 3. send each part of the file to its operation;+ 4. `PATCH /v1/buildUploadFiles/{id}` with `uploaded: true` and the file's MD5;+ 5. poll `GET /v1/buildUploads/{id}` until its state is complete (or failed, with the reason).++ The build shows up in TestFlight after Apple's processing. Internal testers get it at once; the+ public beta (https://testflight.apple.com/join/RKATb61k) after Beta App Review. Submit it for+ App Store review from there.++#### Animation packs (Background Assets)++The sharper animation qualities are Apple-hosted asset packs (iOS 26), one per quality and+figure (`anim-<px>-male`, `anim-<px>-female`), on demand. They change only when the animations+do, not with every release, and are uploaded once per change, separate from the build.++1. `node scripts/media/make-pack-manifests.mjs <out>` writes per pack the drawing ids and the+ manifest (`fileSource` `<px>/<id>.webp`, `fileDestination` `<packId>/<id>.webp`), from the+ catalogue's names only; it never opens a media file.+2. `xcrun ba-package package <packId>/manifest.json -o <packId>.aar` turns each manifest plus the+ private quality folders (its `sourceRoot`, one folder per quality) into the pack's archive.+ This needs Xcode 26 or later: the one release step that needs a Mac of our own.+3. Upload through the App Store Connect API, per pack: find or create it+ (`GET /v1/apps/{id}/backgroundAssets?filter[assetPackIdentifier]=…`, `POST /v1/backgroundAssets`),+ `POST /v1/backgroundAssetVersions` (Apple numbers it), `POST /v1/backgroundAssetUploadFiles`+ (name, size) for the `uploadOperations`, send the parts, `PATCH` it with `uploaded: true` and+ the MD5, then poll the version until it is `COMPLETE`. A complete version is available to+ internal TestFlight by itself; external TestFlight and the App Store take it with their review+ submission.++The full-quality files only ever travel from the release machine to Apple, like the IPA (licence).## One-time setup (owner)@@ -117,7 +164,11 @@ on the phone (Settings → Reset, or uninstall).- `openssl req -new -newkey rsa:2048 -nodes -keyout dist.key -out dist.csr -subj "/CN=Duarte Santos/emailAddress=…"`,upload the CSR under Certificates → Apple Distribution, download `distribution.cer`, then`openssl x509 -inform der -in distribution.cer -out dist.pem && openssl pkcs12 -export -legacy -inkey dist.key -in dist.pem -out dist.p12`.- - Profiles → App Store Connect profile for `ch.opengym.app` → `openGym_AppStore.mobileprovision`.+ - Profiles → an App Store Connect profile for `ch.opengym.app` → `openGym_AppStore.mobileprovision`,+ and one each for `ch.opengym.app.AnimationPacksDownloader`, `ch.opengym.app.widgets`,+ `ch.opengym.app.watchkitapp` and `ch.opengym.app.watchkitapp.widgets`. The app, the downloader,+ the widgets and the watch widget share the App Group `group.ch.opengym.app`; the app and the+ watch app have HealthKit.- Users and Access → Integrations → App Store Connect API key (Admin) for uploads; with it thebundle id, certificate and profile can also be created through the API instead of the portal.- Keep all of it next to the Android keystore (`/root/.config/opengym/`, never in a repo).diff --git a/docs/MOBILE.md b/docs/MOBILE.mdindex c283d4b0c..cc161e7cf 100644--- a/docs/MOBILE.md+++ b/docs/MOBILE.md@@ -207,8 +207,8 @@ 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 anapp 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+ 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, called from Java(`HealthConnectPlugin.java`) through `runBlocking` on a worker thread, so the Android project staysJava-only. 1.1.0 stable needs compileSdk 36 and AGP 8.9.1, a toolchain bump left for its ownchange. The library asks for minSdk 26; `tools:overrideLibrary` keeps the app at 23 and the plugin@@ -229,7 +229,8 @@ and **Delete**.- **Licence first.** The animations are licensed from Gym visual. The repository, the web buildand every self-hosted server only ever have the 180 px files. Anything larger reaches peopleonly inside the official store apps: built into the package, or as an **Apple-hosted asset pack**- (Background Assets, iOS 26) that Apple delivers, later a Play asset pack. Never from a server of+ (Background Assets, iOS 26) or a **Play asset pack** (Play Asset Delivery) that the store+ delivers. Never from a server ofours, never at a URL anyone can fetch. No tool here opens a media file; packs are planned fromfile names alone.- **The packs.** One per quality and figure: `anim-<px>-male`, `anim-<px>-female` for 240, 360,@@ -260,8 +261,13 @@ and **Delete**.Info.plist keys `BAAppGroupID`, `BAHasManagedAssetPacks`, `BAUsesAppleHosting`, and the AppGroup `group.ch.opengym.app` on the app and the extension. `scripts/ios/finish-ipa.sh` signs theextension 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:** in the `play` flavour the same interface goes through Play Asset Delivery (status,+ download with progress, Wi-Fi only with Play's own prompt for mobile data, remove) for the packs+ its `assets/anim-packs.json` lists, and serves their files to the page at+ `https://localhost/_opengym_pack/<packId>/<drawing>.webp`, never a file path. The pack modules+ are generated on the release machine by `scripts/android/make-asset-packs.mjs` and never+ committed. The `sideload` flavour (the APK) answers "unavailable" and only ever has its+ built-in animations (240 px).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@@ -278,7 +284,7 @@ cellular with Wi-Fi only on, it waits; Still only shows stills everywhere a work- **Android:** Android Studio (bundles the SDK). Java 21 for Gradle.- **iOS:** a Mac with Xcode 15+ and CocoaPods (`brew install cocoapods`). A free Apple IDis 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.+ for App Store and TestFlight distribution ([APP_STORES.md](APP_STORES.md)).## Build & run@@ -310,10 +316,12 @@ npx @capacitor/assets generate --iconBackgroundColor '#0c0e12' --splashBackgroun(If the generator won't take the SVG directly, export it to `resources/icon.png` at1024×1024 first — any image tool can do it.)-## Distribution — deliberately no app stores+## Distribution-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.+The signed APK stays the way to get openGym on Android without a store, and it updates itself.+The App Store app (public TestFlight beta: https://testflight.apple.com/join/RKATb61k) and the+Google Play build come from the same code; how they are built and uploaded is in+[APP_STORES.md](APP_STORES.md).### Android — sideload the APK@@ -366,8 +374,10 @@ apksigner sign --ks my.keystore --ks-key-alias opengym --out openGym.apk aligned> The App Store and Google Play builds, and how a release gets there: [APP_STORES.md](APP_STORES.md).-Apple does not allow installing apps outside the App Store, so there is no `.ipa` download-that would simply install. Your free options:+The App Store app, or before it is out the public TestFlight beta+(https://testflight.apple.com/join/RKATb61k), is the easy way. Apple does not allow installing+apps outside the App Store, so there is no `.ipa` download that would simply install. Without the+store, your free options:- **Self-host + PWA** (recommended): open your instance in Safari → Share → *Add to HomeScreen*. Full-screen app, no expiry, plus sync and passkeys.@@ -384,9 +394,9 @@ free tier. To switch it on, register a Mac as a project runner (shell executor;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 existsthe 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.+The signed App Store and TestFlight builds don't come from this job: GitHub's `iOS` workflow+archives them unsigned and the release machine finishes, signs and uploads them+([APP_STORES.md](APP_STORES.md)).### Release notes for maintainers