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.
The phone app (Android and iOS)
Just want the app? See 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 and connecting it to your server. Everything from Prerequisites on is for building the app yourself.
Getting the app
| Where | Updates | |
|---|---|---|
| iPhone and iPad | The App Store. To test the next version early: the public TestFlight beta | the App Store or TestFlight |
| Apple Watch | Comes with the iPhone app | with the iPhone app |
| Android, APK | GitHub release or opengym.ch. From v1.4.2 in three sizes: Standard (animations at 180 px), Plus (240 px) and HD (360 px, the biggest 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, Plus and HD, without losing its data. How the store builds are made and released is in APP_STORES.md.
How the phone app works
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 |
| 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/) |
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
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, 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.
Passkeys can't be used for this: the app's WebView runs at its own origin, which never matches the real hostname WebAuthn needs. Instead you pair the device from a browser that's already signed in: Settings → Account → "Pair the mobile app" first asks you to confirm it's you (your passkey, or your password where password sign-in is on), then shows a one-time code (valid 5 minutes, and a new one is a tap away once it runs out); enter your server's address and that code in the app (same first-launch screen, or Settings → Account → "Connect to my server" later) to finish. Notes:
- Works offline too: the phone keeps its copy (and the file mirror) while connected, and changes made without a network go to the server as soon as it is reachable again.
https://is best: it keeps the pairing code and the bearer token (the connection carries one instead of a cookie) off the network in plain text. A plainhttp://server on your home network works too since v1.3.11 (Android; #428): type the address withhttp://in front, for examplehttp://192.168.1.20:8080. An address without a scheme is tried ashttps://, and when that gets nowhere on a home address, pairing tells you to addhttp://. The app also reminds you that http is not encrypted, so keep it to your own network. Your browser still needs a password to sign in there and make the code: passkeys only work over https (orlocalhost).- Pairing says your server "refused the app's request (CORS)", or that "a login page or proxy
rule replied instead of openGym", or fails with "Failed to fetch" on an older version, while
the browser works? Something in front of openGym is answering the app instead: a reverse proxy
handling the CORS preflight itself, adding a second
Access-Control-Allow-Origin, or SSO / forward-auth on/api/. openGym answers the preflight and does its own sign-in; see Phone app and CORS for the fixes and acurlself-check. - The token lasts
SESSION_DAYS(90 by default, seedocs/SELF_HOSTING.md) and renews itself: every time the app starts, a token past half its life is swapped for a fresh one. A phone that is used at all never runs out; one left unopened for longer thanSESSION_DAYShas 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
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/createand/api/pair/redeeminapi/server.jsfor 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 changes on the phone and adds them back the next time it is paired with the same server and account.
A server behind Cloudflare Access
If your server sits behind Cloudflare Access (Zero Trust), the app can't do Access's interactive sign-in from inside its WebView. Use a service token instead:
- In Zero Trust → Access → Service Auth, create a service token and note its Client ID and Client Secret.
- In the Access application for your openGym host, add a policy with the Service Auth action that includes that token.
- 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 gets through. The openGym API answers the preflight itself and allows both headers.
- 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 values, then pair as usual. They can be changed later under Settings → Server & sync → Cloudflare Access.
The app then sends CF-Access-Client-Id and CF-Access-Client-Secret with every request to
the server address they were entered for (scheme, host and port), including the pairing itself,
and with nothing else: a pairing with any other address goes without them. Disconnecting from
the server removes them. Both are kept in the phone's secure storage (Android Keystore / iOS
Keychain), never in synced data or backups.
Connection states
Settings → Account → Server & sync shows the server, the account, how things stand, when the phone last held exactly what the server holds, how many changes are still waiting, and a Sync now button that says how it went. Whenever the app is not connected, a line under the 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. |
| 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 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 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 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.jsonin the app's private data directory: the durable copy of everything on the phone, written after every change (not reachable without a rooted phone oradbon a debug build).opengym-state-owner.jsonbeside 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 account pairing, waiting for their server and account.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 file per day; each new copy deletes all but the newest 14 of these dated files in that folder. Nothing else is deleted, in that folder or anywhere: other files you keep there, and the copies versions before 1.3.9 wrote straight intoDocuments/, 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, 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 toDocuments/openGymagain and Settings says so until you choose the folder again or tap Use default folder.
Photos and videos of your own exercises
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 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.
- Where it lives:
Library/opengym-media/in the app's own storage (iOS's Library folder, Android's files directory), one file per photo or video named by its SHA-256, plus a smallindex.json. The state keeps only a reference of a few hundred bytes. A MOV is stored with an.mp4name so the WebView plays it. - Local mode: that folder is the only copy. Export with photos & videos (.zip) in Settings → Data & backup writes a zip with the usual JSON backup and every file, through the share sheet; Import backup takes that zip back. The daily auto-backup stays JSON only.
- Paired with a server: files go up to the server (
PUT /api/media/{hash}) and come down with the phone's token into the same folder, so they show offline too. A file that has not 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 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
(
NSCameraUsageDescription, now also for photos and videos of exercises) and, to record a video with sound from the picker, the microphone (NSMicrophoneUsageDescription).
Worth checking on a real device after changes here, since no test runs a WebView: a short
video autoplays muted in the Android WebView; a long video seeks from its _capacitor_file_
URL on both platforms; an iPhone photo arrives as JPEG and an iPhone video (HEVC or H.264 MOV)
plays; the zip export opens the share sheet.
Health Connect (Android)
Settings → Health Connect writes finished workouts and weigh-ins to Health Connect, Android's on-device store for health data, where other apps (Google Fit, Samsung Health, a smartwatch app…) 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
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).
Each weigh-in as a weight record, in kilograms. A workout without a real start and end is left
out rather than given made-up times.
src/lib/health-connect.jsworks this out; its tests pin it. - Permissions. The manifest declares
WRITE_EXERCISE,WRITE_WEIGHTand, since v1.4.3,READ_HEART_RATEandREAD_WEIGHT(see "Reading back" below). Each is asked for only when its switch is turned on. No background and no history permission. - No duplicates. Every record carries openGym's own id as its
clientRecordId(opengym-w-<workout id>,opengym-bw-<day>), so writing it again replaces it. An edited workout or weigh-in is written again; a deleted one is removed from Health Connect. - This phone only. Whether it is on, and a fingerprint of each record already written, live in
opengym-health.jsonin the app's data directory, never in the synced state: it does not travel to a server, into a backup export, or to a second phone. It works the same in local mode and paired with a server, because the writing happens on the phone. - When it writes: after each save (finishing a workout, a weigh-in, an edit), when the app comes back to the foreground, and once at launch. While it is off, a save costs nothing: the file is read once at launch and kept in memory.
- Turning it off asks whether to keep what openGym wrote in Health Connect, as the user's own 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 7) Health Connect does not exist and the card is not shown.
- The library:
androidx.health.connect:connect-client1.1.0 (the version is pinned inandroid/variables.gradle), called from Java (HealthConnectPlugin.java) throughrunBlockingon a worker thread, so the Android project stays Java-only. The library asks for minSdk 26;tools:overrideLibrarykeeps the app at 24 (Android 7.0) and the plugin checks the version before touching it. - Privacy link. Health Connect's "why does this app ask?" link opens the app through the two
activity-aliases in the manifest;
MainActivitythen opens https://opengym.ch/privacy, the same policy the Play listing names (Play requires that).
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 in openGym removes it there; turning it off with "remove" leaves no openGym record behind.
Reading back: heart rate and weigh-ins (v1.4.3, #544, #127)
Two more switches in the same card (Android: Health Connect, iPhone: Apple Health), each off by default, each independent of writing and of the other:
- Heart rate from your watch. For each workout finished in the last 24 hours, the heart-rate
samples between its start and end (+5 min) are read:
HC.readHeartRate({ from, to })→{ samples: [[ms, bpm]] }.lib/heart-rate.jshrFromSamplessplits them over the sets: a set ends at its tick (at) and lasts as long as its reps (3 s each, 15-120 s), seconds or minutes take, never starting before the previous tick (the same estimate as the .fit export); its rest runs to the next set. A set getshr/restHr({ avg, max }, the Apple Watch fields) only when it has none yet, so the Apple Watch's live reading is never replaced. Sparse sources (median gap over 20 s, a band that saves once a minute) and workouts without ticks get only the session's reading,w.hr = { avg, max, src: 'hc' | 'ah', n }, replaced later only by a fuller read from the same hub (Garmin and Fitbit sync late) and never whensrcis'watch'. Re-read at most every 10 minutes (2 after coming back to the foreground) until the 24 hours are over. - Weigh-ins from other apps.
HC.readWeights({ since })→{ records: [{ t, kg, id, origin, clientId }] }: 30 days back the first time (what Health Connect gives without the history permission), afterwards from the newest seen minus two days.lib/health-read.jsmergeWeighInstakes the latest of each day, skips openGym's own records (clientRecordIdopengym-*, originch.duartesantos.opengym*), keeps a day that has a weigh-in typed into openGym, does not bring back one deleted in openGym after it was measured, and converts to lb for an lb profile. Imported entries carrysrcand are never written back (healthRecordsleaves them out), and in a sync merge a typed weigh-in beats an imported one of the same day whichever is newer (mergeBodyweight); typing over an imported one makes it a typed one. - Foreground only. Reads run at launch, on resume and after saves, never in the background.
No
READ_HEALTH_DATA_IN_BACKGROUND, noREAD_HEALTH_DATA_HISTORY; old workouts are not filled in. - Device-local state in
opengym-health.json:readHr,readWeight,wCursor,seen(what was imported per day),hrTried(when each recent workout was last read),readError. - iPhone:
AppleHealthPlugin.swiftreadHeartRate/readWeightsthroughHKSampleQuery; the plain-value conversion isWatchCore/Sources/WatchCore/HealthReadCore.swift(compiled into the app, tested byswift test). Apple Health never says whether reading was allowed, so a refusal reads nothing. The usage string (NSHealthShareUsageDescription) says what is read. - Synced fields:
set.hr,set.restHr,w.hr,bodyweight[].srcare plain optional fields; the server keeps them through every writer (api/test/sync-hr.test.js). - Emulator check: Google's Health Connect Toolbox can insert heart-rate and weight records on an API 34+ emulator; see the v1.4.3 notes for the run.
Animation quality and the animation packs (store apps)
Settings → Workout → Animation quality, in the store apps only (the web and a self-hosted server show nothing new): Auto (360 px on a phone, 720 px on a tablet), Still only (no animation, just the still), Built in (the files inside the app), or 240, 360, 480, 720 or 1080 px. Plus Download over Wi-Fi only (on by default) and, per pack on the device, its size and Delete.
- Licence first. The animations are licensed from Gym visual. The repository, the web build and every self-hosted server only ever have the 180 px files. Anything larger reaches people only inside the official store apps: built into the package, or as an Apple-hosted asset pack (Background Assets, iOS 26) or a Play asset pack (Play Asset Delivery) that the store delivers. Never from a server of ours, never at a URL anyone can fetch. No tool here opens a media file; packs are planned from file names alone.
- The packs. One per quality and figure:
anim-<px>-male,anim-<px>-femalefor 240, 360, 480, 720 and 1080, all on demand. A figure's pack holds every drawing that figure shows: per catalogue exercise its drawing for that figure, or its own when it is drawn once (those are in both packs). Inside a pack a drawing sits at<packId>/<drawing id>.webp, so the male and the female pack of a quality (which share every drawing made once), or two qualities, never claim the same path in the one tree Background Assets reads all packs as.node scripts/media/make-pack-manifests.mjs <out>writes, per pack, the ids and the manifestxcrun ba-packagetakes (fileSource<px>/<id>.webp, relative to a source root with one folder per quality), plus a summary.--layout clipwritesclip/<id>.webpinstead. - What shows (
src/lib/anim-quality.js,clipSources): the chosen quality's pack for the figure shown if it is installed, else the next smaller installed pack of that figure, else the built-in file, then the still. Never a blank, and never the other figure's drawing. Custom exercises keep their own media (components/CustomMedia.jsx) and never go through any of this. - Downloads. Choosing a quality whose pack is not there starts its download for the figure shown, and the built-in animations show meanwhile; switching the figure (Look & Home → Exercise drawings) fetches the other figure's pack of that quality. Auto does the same, over Wi-Fi.
- This device only. The choice is kept in the WebView's localStorage (
gym_anim_v1), never in the synced profile: packs are downloaded per device, and a phone and an iPad want different sizes. Switching quality or figure never writes the profile;src/lib/anim-data-safety.test.jsholds that, and that every exercise a profile refers to keeps a picture at every quality. - iOS:
AnimationPacksPlugin.swift(AssetPackManager: status, download with progress, remove, the folder of a pack's files). Before iOS 26 it answers "unavailable" and the setting offers only Still only and Built in. Apple-hosted packs need the downloader extensionios/App/AnimationPacksDownloader(aStoreDownloaderExtension), added and embedded byios/ci/add-asset-downloader.rb(run once and commit the project; CI runs it until then), the Info.plist keysBAAppGroupID,BAHasManagedAssetPacks,BAUsesAppleHosting, and the App Groupgroup.ch.opengym.appon the app and the extension.scripts/ios/finish-ipa.shsigns the extension with its own profile (EXT_PROFILE). - Android: in the
playflavour 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 itsassets/anim-packs.jsonlists, and serves their files to the page athttps://localhost/_opengym_pack/<packId>/<drawing>.webp, never a file path. The pack modules are generated on the release machine byscripts/android/make-asset-packs.mjsand never committed. Thesideloadflavour (the APKs) answers "unavailable" and only ever has its built-in animations: 180 px in the Standard APK, 240 px in Plus, 360 px in HD. Each APK's updater stays with its own kind (pickApkinlib/update.js, told byVITE_APK_VARIANT).
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
ch.opengym.app and on the extension, both with that group; an App Store provisioning profile
for each; then the ten packs uploaded as Apple-hosted background assets for the app.
Worth checking on a device: picking 720 px starts a download that shows its progress; the animation sharpens once it is done; Delete frees the space and the animation falls back; on cellular with Wi-Fi only on, it waits; Still only shows stills everywhere a workout shows media.
Gym reminder (#614)
Settings → Reminders → Gym reminder, in the phone app only (the web build has no such page: a browser cannot watch where you are with the page closed). Off by default. Add gyms with "I'm at the gym right now" (the phone's position) or a pin on an OpenStreetMap map (Leaflet; the address search asks Nominatim, only on an explicit tap of Search, with a User-Agent naming the app). Each gym has a radius (100 m by default, 50 to 500) and an optional text. Up to 20 gyms (iOS watches at most 20 regions per app). Walking into one posts "Gym spotted. Ready for your workout? 💪"; a tap opens the Start screen (or the running workout).
- No nagging (
src/lib/gym-reminder.jsskipReason, the same rule inGymReminderRules.javaandios/App/GymReminderCore): at most once a day, not after a workout logged today, not on a day note that excuses today, not while a session started in the last 12 hours runs, and only inside the optional time window (an overnight one wraps). The phone decides when the gym is entered, from what the page last told it (GymReminder.status, sent after every save of the profile and on every return to the app). - Trained on another device? A workout logged on the web or another phone that this phone has
not synced yet: before posting, a paired phone asks its server (
GET /api/nudge-check, the same few bytes the missed-day check uses) whether today is done, bounded to 3 seconds (Android: a future with a timeout aroundHttpURLConnection, so a hanging DNS lookup cannot stretch it; iOS: an ephemeralURLSessionwith 3 s timeouts plus a hard stop). "Done" keeps it quiet and is remembered for the rest of the day. No server (local only), offline, an error or no answer in time: the phone's own status decides, as before. The page hands over the server and its headers withGymReminder.server(lib/gym-reminder.jspushGymServer); Android keeps them encrypted with the app's Keystore key (NudgeCheck.seal), iOS in the Keychain (this device only). - Locations stay on the phone. The gyms live only in the native side's own storage: Android
shared_prefs/opengym_gym_reminder.xml, left out of cloud backup and device transfer (res/xml/*_rules.xml); iOSApplication Support/gym-reminder.json, excluded from backups. The WebView's storage keeps only an on/off flag (it is part of phone backups), the synced profile and backup files never see any of it. - Android: the platform's proximity alerts (
LocationManager.addProximityAlert), no Google Play Services, so the APK and F-Droid builds have it too. Location while in use is asked when you add a gym from where you stand; "Allow all the time" (ACCESS_BACKGROUND_LOCATION) only after the in-app explainer, and from Android 11 on that is the system's settings page.GymReminderReceivergets the alert,GymReminderBootReceiverregisters the alerts again after a restart or an app update. An alert added while you are already inside reports an entry at once; entries in the first 90 s after arming are ignored. How soon an entry is noticed is the system's call: Android's geofencing service asks for a fix only every 30 min for a background app (location_background_throttle_proximity_alert_interval_ms) and otherwise piggybacks on fixes other apps cause. On a phone with Google Play Services those come often; on a phone without (and indoors, where GPS may not get a fix at all) the nudge could come half an hour late. - Approach check (Android): every gym also gets a wide proximity alert, the approach zone
(800 m, or 5× the radius for big ones;
GymReminderRules.approachOf). Entering it startsGymScanService, a location foreground service that asks for a fix every 15 s (fused, high accuracy) and stops at the first of: inside a gym (then the usual no-nag rule and the server check decide), beyond every approach zone + 250 m, today settled meanwhile, or 15 minutes. At most 3 checks a day, none once today is settled (fired, trained, excused, outside the window), so a normal day costs one check of a few minutes and the worst case is 45 min of GPS. Its notification is a silent one on its own channel (gym-reminder-check, IMPORTANCE_MIN) and goes away with the check (Android holds a new foreground-service notification back for up to 10 s, so a check that ends quickly may never show one). Catch: Android 12+ lets a background app start a foreground service only with an exemption, and a proximity alert is not one (checked on the emulator:ForegroundServiceStartNotAllowedException). It works with openGym's battery use on Unrestricted (started directly) or with "Alarms & reminders" allowed (an exact alarm half a second later starts it); the gym page shows this as "Quick arrival check" and leads to the app's settings. Without either, the gym's own alert still fires on the system's schedule. Trade-offs considered: the Play Services Geofencing API would give ~2 min latency on theplayflavour without any of this (and its transitions do exempt a service start), but adds a Google dependency and a second code path; a periodic location poll would cost battery all day for one arrival. Google Play: theplayflavour now also declares alocationforeground service type, which needs the foreground-service declaration in the Play Console next to the background location one (same feature, same video). - iOS: region monitoring (
CLLocationManager,GymReminderPlugin.swift). Needs Always location and Precise Location; no background location mode is declared (region monitoring does not need one). iOS relaunches the app in the background on arrival;AppDelegatemakesGymReminderCenterthe location delegate at launch so the event lands. On an iPhone with an Apple Watch the notification shows on the watch as usual.
Testing on the Android emulator: scripts/android/gym-reminder-emulator.sh <debug apk> saves a
gym, moves the phone far away and then inside the radius, and checks the notification, the tap
(lands on #/workout) and the no-nag rules. adb emu geo fix alone is not enough there: it feeds
the GPS provider, while proximity alerts are fed by the fused provider, so the script replaces that
with a shell test provider (cmd location providers ...). Android polls proximity alerts at most
every 30 min on its own (location_background_throttle_proximity_alert_interval_ms), faster
whenever other apps get fixes; the script lowers it to 15 s. On a real phone that means the nudge
usually comes within minutes, at worst about half an hour after you walk in.
scripts/android/gym-reminder-approach-emulator.sh <debug apk> (EXEMPT=battery|alarm|none) proves
the approach check with the throttle left at Android's default: the app is closed, the phone
waits in the approach zone, the check starts (its location request shows in dumpsys location),
then the phone walks in at 1.4 m/s and the time from crossing the radius to the notification is
measured; then the server check against a fake paired server on the host (trained elsewhere:
quiet; a black-holed server: posts after the 3 s bound; no server: posts).
Prerequisites
- 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 and TestFlight distribution (APP_STORES.md).
Build & run
cd frontend
npm install
npm run build:mobile # VITE_MOBILE build + `cap sync` into android/ and ios/
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 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/distcontains the mobile bundle. Run a plainnpm run buildagain before deployingdistto a server.
App icons & splash screens
frontend/resources/icon.svg is the 1024×1024 source (the app's dumbbell glyph on the
app background). Generate all platform assets from it on a machine with the tooling:
cd frontend
npx @capacitor/[email protected] generate --iconBackgroundColor '#0c0e12' --splashBackgroundColor '#0c0e12'
The generator is not a dependency of the app (it pulls in an old Capacitor CLI and sharp),
so npx fetches it for that one run.
(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.)
The alternate icons people can pick in Settings → Look & Home → App icon (iPhone only in 1.4.3;
Android gets them in 1.4.4) are not made by that generator. node scripts/app-icons.mjs draws
them from the list in src/lib/app-icon-variants.js and the glyph in resources/icon.svg, with
no dependencies: the SVG per icon in resources/icons/, an AppIcon-<Name> set (1024 px, opaque)
per icon in the iOS asset catalog, and the previews in public/app-icons/. An icon with art
(Halloween) is a hand-made SVG in resources/icons/ instead, which the script renders; it may use
only rect, circle, line, polyline, polygon and one two-stop radialGradient. --check says whether
the committed files still match. A new icon also needs its name in AppIconPlugin.swift and its
set in ASSETCATALOG_COMPILER_ALTERNATE_APPICON_NAMES; scripts/app-icons.test.mjs fails until
all of them agree.
Distributing your own build
The signed APK stays the way to get openGym on Android without a store, and it updates itself. The App Store app and the Google Play build come from the same code; how they are built and uploaded is in APP_STORES.md.
Android: sideload the APK
Every release has three signed APKs on the GitHub release,
each with its .sha256 beside it, and opengym.ch links to all three:
openGym-X.Y.Z.apk(Standard): the exercise animations built in at 180 px, about 315 MB.openGym-Plus-X.Y.Z.apk(Plus): the same app with 240 px animations, about 424 MB.openGym-HD-X.Y.Z.apk(HD): the same app with 360 px animations, about 760 MB.
Same app id, same key: install one over another and the data stays. The in-app updater keeps
each on its own kind. Android asks you to allow installs from the browser the first time; that's
standard for any app from outside Google Play. Check the .sha256 if you got the file from
anywhere else.
The release APKs are built and signed on the release machine (scripts/android/build-release.sh,
APP_STORES.md), not in CI, 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); its releases link to GitHub's.
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
alone. A debug build (./gradlew assembleDebug) keeps all four, so it still runs on an x86_64
emulator.
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,
# or Android refuses to install the new version over the old one.
keytool -genkeypair -keystore my.keystore -alias opengym -keyalg RSA -validity 10950
# align + sign (zipalign/apksigner ship with the Android SDK build-tools)
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: build it yourself
The App Store app is the easy way. If you want your own build, for example of a fork:
- 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 / 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/versionCodeinandroid/app/build.gradleper release, andMARKETING_VERSION/CURRENT_PROJECT_VERSIONin the iOS project; keep them in step withfrontend/package.json.versionCodemust strictly increase or updates won't install over an existing APK.scripts/android/build-release.shrefuses to build whenpackage.jsonandbuild.gradledisagree. The full release list is in 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.mdcarries an app-store exception (an additional permission under AGPL §7) granted by the copyright holder, and the CLA 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_ALARMso the reminder fires to the minute where the user allows exact alarms (Android 14 no longer grants it at install). The opt-in missed-workout nudge is scheduled the same way, beside the reminder: one notification on the evening (20:00–21:30) of each upcoming planned day, at most 3 past the last workout, rescheduled whenever a workout is logged. A workout logged on another device (the web, a second phone) reaches these only when the app syncs, so a paired phone also runs a background check before them (lib/nudge-check.js, the nativeNudgeCheckplugin): it asks the serverGET /api/nudge-check?date=…(a few bytes: was the day trained or excused, would the server still nudge it) and takes back that day's reminder and nudge when the answer says so. Offline, an error or no answer leaves everything as it was, and the app resyncs in full whenever it is opened. On Android aJobSchedulerjob runs in the half hour before the notification, with a network if there is one. On iOS it is aBGAppRefreshTaskasked for an hour before, and iOS decides when it actually runs: it learns from how often the app is opened, holds back in Low Power Mode, and never runs it after the app was swiped away from the app switcher or with Background App Refresh off, so there the check is a good chance, not a promise. The pairing token it needs is kept in the Keychain (iOS) or encrypted with a Keystore key (Android). The rest countdown does not depend on it: a foreground service (specialUse) keeps the countdown in the notification and holds a wake lock until the end, so the end of a rest sounds on time with the screen locked; the rest-over alarm is only its fallback.