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
Self-hosting: the web container passes photo and video uploads straight through to the API, and the docs say what a proxy in front needs, what is kept and for how long
Duarte Santosd545600ccd58
diff --git a/.env.example b/.env.exampleindex 99701867c..02a41f69c 100644--- a/.env.example+++ b/.env.example@@ -144,7 +144,8 @@ RP_NAME=openGym# DATA_DIR is the one directory the API stores anything in: db.json (accounts,# passkey credentials, push subscriptions, invites), state-<uid>.json per# profile, `secret` (the key every session cookie is signed with), vapid.json,-# audit.log, and the Coach's coach.json and coach/ when it is on. Back up that+# audit.log, uploads/ (the photos and videos of custom exercises), and the+# Coach's coach.json and coach/ when it is on. Back up that# directory and you have backed up the instance; lose `secret` and everyone is# signed out. Default /data.#@@ -159,6 +160,41 @@ RP_NAME=openGym## DATA_DIR=/data+# ── Photos and videos of custom exercises (optional) ───────────────────────+# People can give an exercise they made a photo, a GIF or a short video. It is+# stored on this server under ./data/uploads/<profile>/ and only its owner can+# read it back. On by default with the limits below; every MB is 1024×1024+# bytes. Turn it off entirely (the app then offers a link field only):+#+# MEDIA_UPLOADS=0+#+# Space per profile (0 = no cap), and per file. Photos are shrunk on the+# device before upload (1600 px), so 2 MB is plenty; videos are not shrunk.+#+# MEDIA_QUOTA_MB=200+# MEDIA_IMAGE_MAX_MB=2+# MEDIA_GIF_MAX_MB=8+# MEDIA_VIDEO_MAX_MB=40+# MEDIA_VIDEO_MAX_SEC=60+#+# A file nobody's exercise uses any more is deleted after this many days (other+# devices may still show it until they sync):+#+# MEDIA_GC_GRACE_DAYS=14+#+# Uploads per profile per hour, and the free disk space below which uploads+# are refused so a full disk cannot take the rest of the instance with it.+# On an instance with open signup, lower MEDIA_QUOTA_MB too: the worst case is+# the quota times the number of profiles.+#+# MEDIA_UPLOADS_PER_HOUR=600+# MEDIA_MIN_FREE_MB=512+#+# The web container's own cap on an upload. Keep it above MEDIA_VIDEO_MAX_MB,+# and give any reverse proxy in front the same room (docs/SELF_HOSTING.md):+#+# MEDIA_UPLOAD_MAX=48m+# ── Notifications (optional) ───────────────────────────────────────────────# Push works out of the box — nothing to set. VAPID keys are generated on first# run and saved to ./data/vapid.json. Each user's browser reports its owndiff --git a/SECURITY.md b/SECURITY.mdindex 07d74b141..9736b826c 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -162,6 +162,22 @@ Read this before hosting openGym for anyone other than yourself.(a stalling endpoint used to hang the request handler indefinitely), run at most 6 at a time,and each account is capped at 20 subscriptions, so one small request cannot become an unboundedburst of outbound connections (`api/server.js:108-110`).+- **An uploaded photo or video can only be one of seven file types, and only its owner gets it+ back.** People can attach one photo, GIF or short video to an exercise they made. The server+ decides what a file is from its first bytes, never from its name or the type the client+ declared, and stores JPEG, PNG, WebP, GIF, MP4, MOV and WebM only — SVG, HTML and everything+ else is refused. It never decodes a file, so there is no image or video parser to attack. Each+ file is named by its SHA-256, which the upload has to match, and kept per profile in+ `./data/uploads/<uid>/` (folders `0700`, files `0600`, out of the Coach runtime's reach). It is+ served to its owner only — no admin, Coach or plan-sharing route reads one — with a fixed+ `Content-Type`, `nosniff`, `Content-Security-Policy: default-src 'none'; sandbox`,+ `Cross-Origin-Resource-Policy: same-origin` and `Cache-Control: private, no-store`. Uploads+ need the same session and origin check as every other write, are capped per file, per profile+ (`MEDIA_QUOTA_MB`), to 600 an hour and two at a time per profile, streamed to disk rather than+ held in memory, cut off after 60 s without a byte, and refused when the disk runs low+ (`api/media.js`). The server never fetches anything a user supplies here: an exercise's link+ is only ever opened by its owner's own tap, in a new browsing context with+ `noopener,noreferrer`, and the Coach cannot write one.- **There is an activity log.** Sign-ins, sign-outs, failed and refused attempts, and every adminaction are appended to `./data/audit.log`, one JSON object per line, and shown in the admindashboard. It is on by default (`AUDIT_LOG=0` disables it) and capped at `AUDIT_MAX` events /@@ -178,6 +194,14 @@ Read this before hosting openGym for anyone other than yourself.people, they are trusting you exactly as much as they'd trust any server operator.** With theactivity log on, `./data/audit.log` adds everyone's sign-in times to that — worth rememberingbefore an archive of `./data` goes somewhere you don't run.+- **Photos and videos are not encrypted either, and a removed one lingers.** Whoever can read+ `./data/uploads/` can see every profile's files. A file its owner stopped using is kept for+ `MEDIA_GC_GRACE_DAYS` (14 by default) so their other devices can catch up, unless they use+ "Reset everything". Location data is removed by the app before a file leaves the device, not by+ the server: photos are re-encoded (no EXIF or GPS survives) and the metadata boxes and+ telemetry tracks of MP4/MOV videos are blanked, but WebM videos are uploaded as recorded, and a+ client other than the app can upload a file with its metadata intact — readable, still, only by+ that same profile.- **Admins can read everything.** A user listed in `ADMIN_UIDS` (or flagged `admin: true` in`db.json`) gets every user's full history and body weight, can disable accounts, and can createor revoke invite codes (`api/server.js:825-947`). Off by default — a fresh instance has no admin.diff --git a/docker-compose.yml b/docker-compose.ymlindex 28abd5f42..317ecd5a1 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -57,6 +57,7 @@ services:- TRUST_PROXY=${TRUST_PROXY:-1}volumes:- ./data:/data # users, passkeys, per-user state, session secret — BACK THIS UP+ # (and uploads/: the photos and videos of custom exercises)# Provider credential cache (Codex). A sibling of ./data on purpose: the documented backup# is `tar czf … data/`, and a live refresh token must not end up inside it. Nothing here# needs backing up — if you lose it, sign the provider in again.@@ -93,6 +94,9 @@ services:# slash). Empty serves the app at the site root, which is what it has always done; a proxy# that strips the prefix needs nothing set (docs/SELF_HOSTING.md §5).- BASE_PATH=${BASE_PATH:-}+ # The largest photo or video upload nginx passes to the API. Keep it above+ # MEDIA_VIDEO_MAX_MB (40 by default), which the api service reads from .env.+ - MEDIA_UPLOAD_MAX=${MEDIA_UPLOAD_MAX:-48m}volumes:- ./media/img:/usr/share/nginx/html/img:ro- ./media/gif:/usr/share/nginx/html/gif:rodiff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.mdindex 87561973b..cf92f9662 100644--- a/docs/SELF_HOSTING.md+++ b/docs/SELF_HOSTING.md@@ -88,7 +88,9 @@ gym.example.com {Route `gym.example.com` (HTTPS) → `web:80` (or `<docker-host>:8080`). Any reverse proxy works —openGym only needs the browser to reach it over `https://gym.example.com`. If that proxy capsrequest bodies (nginx does, at 1 MiB by default), allow at least 5 MiB on `/api/` — the app syncs-its whole history in one PUT; the bundled web image already allows 5 MiB, matching the API.+its whole history in one PUT; the bundled web image already allows 5 MiB, matching the API. The+photos and videos people attach to their own exercises need more room and more time on+`/api/media/` — see [Photos and videos of custom exercises](#photos-and-videos-of-custom-exercises).Then set your domain in `.env` and restart:@@ -333,6 +335,59 @@ Either way, keep `ORIGIN` and `RP_ID` pointing at the address in the browser's bsubpath changes nothing about section 2 — but it does mean two instances under one hostname sharea passkey scope and can see each other's credentials. Give each its own hostname if that matters.+### Photos and videos of custom exercises++Anyone signed in can give an exercise they made one photo, GIF or short video (and, separately,+a link, which the server never fetches). The file is uploaded to this server and stored under+`./data/uploads/<profile id>/`, named by its SHA-256. Only its owner can download it again — no+admin route, no Coach and no shared plan reads it. It is on by default, with these limits, all+set in `.env`:++| Variable | Default | Meaning |+|---|---|---|+| `MEDIA_UPLOADS` | `1` | `0` removes the upload routes; the app then offers the link field only |+| `MEDIA_QUOTA_MB` | `200` | space per profile; `0` = no cap |+| `MEDIA_IMAGE_MAX_MB` | `2` | a photo after the app shrank it to 1600 px, and every thumbnail |+| `MEDIA_GIF_MAX_MB` | `8` | an animated GIF |+| `MEDIA_VIDEO_MAX_MB` | `40` | a video, as recorded — the app does not re-encode videos |+| `MEDIA_VIDEO_MAX_SEC` | `60` | a video's length |+| `MEDIA_GC_GRACE_DAYS` | `14` | how long a file nobody uses any more is kept |+| `MEDIA_UPLOADS_PER_HOUR` | `600` | uploads per profile per hour; at most two run at once |+| `MEDIA_MIN_FREE_MB` | `512` | uploads are refused while the disk under `./data` has less free; `0` = no floor |+| `MEDIA_UPLOAD_MAX` | `48m` | the web container's body limit on `/api/media/` (nginx syntax); keep it above `MEDIA_VIDEO_MAX_MB` |++Every MB here is 1024 × 1024 bytes. The API reads the `MEDIA_*` caps; the app gets them from+`/api/config` and refuses a file the server would refuse before uploading it.++**Disk.** The worst case is `MEDIA_QUOTA_MB` times the number of profiles. On an instance with+open signup, lower the quota. `MEDIA_MIN_FREE_MB` stops uploads before they fill the disk — a+full disk is also a state save that cannot land, for everybody.++**A reverse proxy in front** has to let the uploads through, or they fail with a 413 or a+timeout the app can only report as "The server refused the file as too large":++- **Body size**: at least `MEDIA_VIDEO_MAX_MB` on `/api/media/`. nginx allows 1 MiB unless told+ otherwise (`client_max_body_size`); Cloudflare's free plan caps a request at 100 MB.+- **Timeouts**: a 40 MB video over a slow mobile uplink takes minutes. Traefik v3 cuts a request+ whose body is still arriving after its entryPoint's `readTimeout`, 60 s by default — raise+ `entryPoints.<name>.transport.respondingTimeouts.readTimeout` (`600s`, say). nginx's+ `client_body_timeout` counts the gap between two reads, so its default of 60 s is fine. The+ API itself gives a request 30 minutes and drops one that sends nothing for 60 s.+- **Content-Security-Policy**: if the proxy adds one, it must allow `blob:` in `img-src` and+ `media-src`. The app shows the files from its own verified local copy through `blob:` URLs.++**What is removed, and when.** A file goes when its owner's stored state has not used it for+`MEDIA_GC_GRACE_DAYS` (checked every hour), after one hour unused when the owner's quota is full,+at once when the owner uses "Reset everything", and with the profile when an admin deletes it.+Nothing is deleted because a state file does not parse or a profile is missing from `db.json`: a+folder whose profile is not in `db.json` is left alone and logged once. A device that still has a+file the server removed uploads it again.++**Privacy.** The app re-encodes photos on the device, so no EXIF or GPS data survives, and blanks+the metadata boxes and the GPS/telemetry tracks of MP4 and MOV videos. WebM videos are uploaded as+recorded. The server never decodes or changes a file. Like everything else in `./data`, the files+are not encrypted at rest — whoever can read that folder can see them.+## 6. BackupsEverything is in `./data`:@@ -346,6 +401,18 @@ on, `audit.log` with everyone's sign-in times. Worth knowing before you ship thebackup service you don't run. Restore by unpacking it back into the project folder. (Individualusers can also export their own data as JSON from Settings.)+The photos and videos of custom exercises are in `data/uploads/`, and they are most of what makes+the archive large. To leave them out:++```bash+tar czf opengym-backup-$(date +%F).tar.gz --exclude=data/uploads data/+```++Restored without them, every profile is intact, and an exercise whose file is gone shows a+placeholder until one of its owner's devices — each keeps its own copy — uploads it again. When+you move openGym to another server, copy the whole `data/`, `uploads/` included; each person can+also carry their own through Settings → *Export with photos & videos* and import it there.+If you enabled the AI Coach with the Codex provider, note what this archive deliberately does**not** contain: `./coach-auth`, where that provider keeps its refreshable sign-in. It is asibling of `./data` rather than a folder inside it precisely so that a live credential does not@@ -524,6 +591,7 @@ browser (see section 2).| "verification failed" on login | `RP_ID`/`ORIGIN` don't match the URL in the address bar. See the section above — start with what the server logged on startup. || Media didn't download | `docker compose logs media`. Re-run `docker compose up -d`, or run `./scripts/fetch-media.sh`. || Port 8080 already used | Set `WEB_PORT=9090` in `.env` (and update `ORIGIN` for local testing). |+| A photo or video will not upload ("refused as too large", or it stops partway) | A proxy in front caps the body or cuts the request off: see [Photos and videos](#photos-and-videos-of-custom-exercises) for the body size and timeouts it needs. || No "Notifications" option in Settings | Requires a signed-in profile and HTTPS (or `localhost`) — guest mode and plain HTTP over LAN can't subscribe. || Day reminder fires at the wrong time | Toggle it off and on in Settings so it re-detects your browser's timezone (also happens automatically on every app load — see section 7). || Notifications switch is off although I turned it on | The server no longer holds the subscription (rebuilt `data/db.json`, regenerated `vapid.json`); the app re-registers on the next start, or switch it on again. On iOS, push only works from the Home Screen icon. |diff --git a/web/Dockerfile b/web/Dockerfileindex 394057b8d..aebb56066 100644--- a/web/Dockerfile+++ b/web/Dockerfile@@ -66,6 +66,10 @@ ENV CF_CONNECTING_IP=""# slash. Empty (the default) serves the app at the root exactly as before. A proxy that strips# the prefix needs nothing here — the app derives the API address from its own URL.ENV BASE_PATH=""+# The largest upload nginx lets through to the API's photo and video route (nginx size syntax).+# Above the API's own video cap (MEDIA_VIDEO_MAX_MB, 40 by default) so the API, which says why,+# is the one that refuses a file — raise both together.+ENV MEDIA_UPLOAD_MAX=48m# Probe the port nginx was actually told to listen on (NGINX_PORT is configurable, so a# hardcoded http://localhost/ breaks on any instance that changed it), and address it asdiff --git a/web/nginx.conf.template b/web/nginx.conf.templateindex e3c8b8df9..2a0d163f1 100644--- a/web/nginx.conf.template+++ b/web/nginx.conf.template@@ -53,6 +53,33 @@ server {proxy_set_header CF-Connecting-IP "${CF_CONNECTING_IP}";}+ # Photos and videos of custom exercises (PUT and GET under api/media/). Nginx picks the+ # longest matching prefix, so this block takes those requests from the one above wherever it+ # sits. Same upstream, resolver and headers; what differs is the body. A video may be tens of+ # MB, so the cap is MEDIA_UPLOAD_MAX (48m by default; keep it above MEDIA_VIDEO_MAX_MB)+ # instead of 5m. The upload is passed to the API as it arrives rather than spooled to a temp+ # file here first: the API checks size, hash and type while it streams and answers a refusal+ # before the rest is sent, and spooling would double the disk writes and hide the progress.+ # The two proxy timeouts are the gaps allowed between two reads or writes on the API side,+ # generous for a slow uplink; a client that stops sending is still cut off by+ # client_body_timeout (60 s between two reads), the same idle limit the API applies itself.+ location ^~ ${BASE_PATH}/api/media/ {+ client_max_body_size ${MEDIA_UPLOAD_MAX};+ proxy_request_buffering off;+ proxy_buffering off;+ proxy_read_timeout 300s;+ proxy_send_timeout 300s;+ resolver ${RESOLVER} valid=10s ipv6=off;+ set $api_upstream http://${BACKEND}:${PORT};+ proxy_pass $api_upstream;+ proxy_http_version 1.1;+ proxy_set_header Host $host;+ proxy_set_header X-Real-IP $remote_addr;+ proxy_set_header X-Forwarded-For $remote_addr;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_set_header CF-Connecting-IP "${CF_CONNECTING_IP}";+ }+# The app routes behind the hash (/#/plan, /#/history …), so a path is never a screen, and the# shell's asset URLs are relative (vite base './' — the Pages demo lives under /demo/). Serving# index.html AT a deep path (/plan/r/x: a typo, a stale link) gave a page whose scripts resolved