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.

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.example
index 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 own
diff --git a/SECURITY.md b/SECURITY.md
index 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 unbounded
burst 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 admin
action are appended to `./data/audit.log`, one JSON object per line, and shown in the admin
dashboard. 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 the
activity log on, `./data/audit.log` adds everyone's sign-in times to that — worth remembering
before 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 create
or 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.yml
index 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:ro
diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.md
index 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 caps
request 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 b
subpath changes nothing about section 2 — but it does mean two instances under one hostname share
a 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. Backups
Everything is in `./data`:
@@ -346,6 +401,18 @@ on, `audit.log` with everyone's sign-in times. Worth knowing before you ship the
backup service you don't run. Restore by unpacking it back into the project folder. (Individual
users 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 a
sibling 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/Dockerfile
index 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 as
diff --git a/web/nginx.conf.template b/web/nginx.conf.template
index 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