openGym self-hosting requirements

Unmodified upstream reference text. Treat instructions in this document as source material, not authorization to act.

Repository

DuarteSantos8/openGym

Source revision

e348fc17c42c7e9a211c5972e573ad3698190ee2

License

AGPL-3.0

Text range

32000–48000 of 52298 characters

Read the pinned upstream source

License and notices: Pinned notice · Pinned notice

Read from the beginning

|
| `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 (a fragmented MP4 that
carries such a track is refused rather than uploaded with it). 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`:

```bash
tar czf opengym-backup-$(date +%F).tar.gz data/
```

That archive contains all profiles, passkeys and workout history — and, if the activity log is
on, `audit.log` with everyone's sign-in times. Worth knowing before you ship the archive to a
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 → Data & backup.)

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 → Data & backup → *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
end up in every backup you are told to make — an archive like this gets copied to laptops and
cloud drives, and a refresh token keeps working wherever it lands. Nothing in `./coach-auth`
needs backing up: if you lose it, sign the provider in again.

API keys for the HTTPS providers (Anthropic, OpenAI, Gemini, a compatible endpoint) are the
other way round: they are in `./data/coach.json`, encrypted with `./data/secret`, so they *are*
in this archive — and unreadable without the secret next to them, like everything else in it.

## 7. Notifications

openGym can push two kinds of alert to your phone/desktop, even when the app isn't open:
rest-timer-over, and a reminder on days you have a workout planned but haven't logged one yet.
Turn it on per-profile in **Settings → Reminders** (requires a signed-in passkey profile and
HTTPS — see section 3).

No setup needed server-side, and nothing to configure per timezone: VAPID keys are generated on
first run and saved to `./data/vapid.json`, and each user's browser reports its own timezone
automatically when they turn the reminder on — it fires at their local time, and follows them if
they travel, regardless of what timezone the server itself runs in.

Under the reminder there is an opt-in **missed-workout nudge** ("Nudge me when I skip a planned
workout", with a tone: Friendly, Guilt trip or Drill sergeant). It is one push on the evening of a
planned day with no workout logged: from 20:00 on the user's clock (or 2 hours after the reminder,
if that is later) until 21:30, and not while a workout is on screen. A rest day never gets one, a
coach week or rotation only counts the second day off in a row, and after 3 missed days in a row
it goes quiet until the next workout is logged. Like the reminder it needs the push subscription
and the reminder switched on; the text is localized from the user's app language.

Where it works: any desktop browser, Android Chrome, and on iOS only the app **added to the Home
Screen** (Safari in a tab has no Web Push). The Android APK's day reminder is a local
notification. Its rest timer is a local alarm: the notification shade shows the time left as a
shrinking bar, and the end alert still fires with the screen off. The lock screen shows that
notification only when notifications are enabled and the system is set to show them there. A paired account still gets the server push if that alarm
cannot be scheduled. A reminder that was due while the server was down or
restarting is still sent up to 15 minutes late, once; the browser re-registers its subscription
with the server on every signed-in start, so a subscription the server lost heals itself.

**Keep screen awake** (Settings → *Workout*) has the same transport requirement: the
Wake Lock API is only available over HTTPS or on `http://localhost`, so on a plain-LAN-IP
instance the switch shows as unsupported. Nothing to configure server-side either way, and iOS
refuses the lock while the phone is in Low Power Mode.

Push services like a contact address for whoever runs the server, in case they ever need to reach
you about your pushes. openGym sends your `ORIGIN` by default; set `VAPID_SUBJECT=mailto:you@example.com`
in `.env` if you would rather they had an inbox.

### Push endpoints on private addresses (`ALLOWED_PRIVATE_IPS`)

The api container resolves push service domains to the IPs. Private IPs are banned by default.
But some DNS setups resolve public domains to private addresses on purpose, for example FakeDNS, a DNS-based proxy or a
split-horizon resolver.
Push then fails and the api log shows `refusing to connect to a private address`.

Set `ALLOWED_PRIVATE_IPS` in `.env` to the private addresses that are safe to reach:

```
ALLOWED_PRIVATE_IPS=198.18.0.0/15
ALLOWED_PRIVATE_IPS=10.0.0.0/8, 192.168.1.50, 172.16.0.1-172.16.0.9, fd00::/8
```

- Separate entries with commas or spaces.
- An entry is a single IP address, a range (`first-last`) or a CIDR block. IPv4 and IPv6 both work.
- An IPv4 entry also covers the same address written as IPv4-mapped IPv6 (`::ffff:10.1.2.3`).
- The default is empty: every private address stays blocked. Keep the list as small as you can —
  each address you allow is an address that a signed-in user can make the server connect to.

## 8. Updating

Running prebuilt images:

```bash
git pull                    # picks up compose/config changes
docker compose pull
docker compose up -d
```

Building from source instead:

```bash
git pull
docker compose up -d --build
```

The app shell is versioned (`?v=N`) so clients pick up changes on next load. Your `./data` is
untouched; the exercise media come with the new image.

## Passkeys fail even though `RP_ID` looks right

The most common support question, and the values are usually *nearly* correct. Work through
these in order — the first two account for most of it.

**1. Ask the server what it actually loaded.** It prints both values on startup:

```
docker compose logs api | grep 'gym-api on'
# gym-api on :3000 (rpID=gym.example.com, origin=https://gym.example.com)
```

If that disagrees with your `.env`, the container is still running the old environment.
`docker compose restart` does **not** re-read `.env` — use `docker compose up -d`.

**2. Check the exact shape of each value.** They are not the same kind of string:

| | Correct | Wrong |
|---|---|---|
| `RP_ID` | `gym.example.com` | `https://gym.example.com`, `gym.example.com:8080`, `gym.example.com/` |
| `ORIGIN` | `https://gym.example.com` | `gym.example.com`, `https://gym.example.com/` |

`RP_ID` is a bare hostname: no scheme, no port, no trailing slash. `ORIGIN` is the full origin
*with* the scheme and *without* a trailing slash. Both must match your address bar exactly.

**3. Behind a tunnel or reverse proxy, use the public hostname.** With Cloudflare Tunnel,
Traefik, nginx or Caddy in front, the browser only ever sees the public name — so that is what
both values must be. Not the container name, not the LAN IP, not the internal port:

```env
RP_ID=gym.example.com
ORIGIN=https://gym.example.com
```

The tunnel's own route may point wherever it likes (`http://localhost:8080` is fine). It is the
browser-facing name that has to appear here.

**4. `www.` is a different host.** A passkey registered on `gym.example.com` will not work on
`www.gym.example.com`. Pick one and redirect the other.

**5. Changing the hostname invalidates existing passkeys.** They were bound to the old one, so
everybody registers again — which is why it pays to settle the domain before others join.

> On a LAN without certificates there is nothing to configure that makes passkeys work over
> plain `http://192.168.x.x`: browsers only allow WebAuthn on HTTPS (or `localhost`). Use guest
> mode, the standalone mobile app (`docs/MOBILE.md`), or put a certificate in front of it.

## Which passkey providers work

openGym asks for a passkey and nothing more specific: no particular kind of device, no platform
authenticator, no attestation, and sign-in lets the browser offer any passkey it can find for
your hostname. So whatever stores passkeys on your device works, and which one you get is
decided by your operating system and browser, not by openGym. The common questions:

**Can I keep my passkey in Bitwarden, 1Password, Proton Pass or another password manager on
Android?** Yes, on Android 14 or later. Switch the app on as a passkey provider in the system
settings (*Passwords, passkeys & accounts*, or *Passwords & accounts*; the name varies by
manufacturer). The system then offers that app when openGym asks to create or use a passkey. If
Chrome keeps offering only Google Password Manager, look under *Autofill services* in Chrome's
own settings for the option to use another service. On Android 13 and earlier, passkeys can only
be stored in Google Password Manager. (#101)

**Firefox on Windows 10 does not offer a QR code to sign in with my phone.** Firefox on Windows
hands passkeys to Windows' own dialog, and the Windows 10 dialog has no *use a phone* option;
Windows 11 added it. On Windows 10, sign in with Chrome or Edge, which show their own QR code, or
keep the passkey in a password manager that has a Firefox extension — or give that PC a passkey
of its own (Windows Hello works in Firefox) with a code from your phone, below. (#103)

**Can one profile have more than one passkey?** Yes. **Settings → Account → Passkeys** lists
them — a name, when each was added and last used — and adds, renames or removes one. Adding one
from there is for anything this browser can reach: another password manager, a security key, or
your phone through the browser's own QR prompt. For a second device that can open openGym itself
(a phone, a work laptop), use **Settings → Account → Add another device**: it shows a code of 12
characters and a QR code of a link that carries it. Scan it with the other device, or type the
code there under **Use a code from your other device** on the sign-in screen; the other device
then creates a passkey of its own and is signed in by it. So a Windows Hello passkey on a PC and
the phone's own passkey can sign in to the same profile, instead of the phone ending up with a
second, empty one. (#95)

Both ways ask you to confirm first — with a passkey the profile already has, or its password
while `PASSWORD_LOGIN=1` — because each adds a lasting way in: a session on its own may be a
copied cookie. Removing a passkey asks for the same, since a copied cookie could otherwise pick
which of your passkeys is left. The code works
once, for ten minutes, and is stored only as a hash; making a new one, signing out everywhere or
changing the password voids it. Wrong codes count toward a per-address pause of code redemption,
like wrong reset codes, and every passkey added or removed and every code made or used is in the
activity log (`auth.passkey.*`, `auth.link.*`).

The last way into a profile cannot be removed: its only passkey stays unless a password can sign
in instead, which counts only while `PASSWORD_LOGIN=1`. Removing a passkey stops it signing in,
but it does not end a session it already opened — sessions are not tied to one passkey. If the
device is lost, remove its passkey *and* use **Sign out everywhere**.

**Where does my passkey live?** Where you created it, and wherever that store syncs: Google
Password Manager to Chrome on your other devices signed in to the same Google account, iCloud
Keychain to your Apple devices, a password manager to every device it runs on. A passkey kept
only on one phone (or on a hardware key) goes with that phone.

**I lost my passkey.** If the profile has another passkey, sign in with that one and remove the
lost one under **Settings → Account → Passkeys**, confirming with the passkey you signed in
with (then **Sign out everywhere**). A browser that is still signed in can give a new device a
passkey with **Add another device** only if the profile also has a password and
`PASSWORD_LOGIN=1`: making the code asks for a passkey or the current password first,
because a session on its own may be a stolen cookie. Otherwise there is no self-service recovery: with `PASSWORD_LOGIN=1` an admin can issue a reset code, and without
it the only way back is a backup (**Settings → Data & backup → Export backup (JSON)**, from any device still
signed in) imported into a new profile. When you ask your admin for help, the id under
**Settings → Account → Account ID** tells them exactly which account is yours. Adding a second
passkey early is what keeps one lost phone from being a lost profile.

The phone app never uses a passkey at all: it pairs with a one-time code from a signed

Read the next section

Search documentation