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: NAS section (Synology, QNAP, Unraid, TrueNAS), password sign-in and guest mode in the FAQ
Duarte Santos361494e3ba44
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 23d9760f2..2754c6335 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -241,6 +241,10 @@ you leave it alone. Handy for deciding whether those legs are really ready (thanbrowser, the app now says which address the server expects and what to change, instead of abare "cross-origin request refused". The server log names the exact `ORIGIN=` and `RP_ID=`to set (thanks tcmac, who lost a morning to this one).+- Self-hosting on a NAS has its own section now: Synology, QNAP, Unraid and TrueNAS, with a+ two-service compose to paste, absolute paths, ports, permissions and HTTPS. The FAQ explains+ password sign-in (`PASSWORD_LOGIN`) and guest mode (`ALLOW_GUEST`), including why a stack+ without its api quietly turns you into a guest.## v1.4.2 (2026-10-18)diff --git a/docs/FAQ.md b/docs/FAQ.mdindex 3e494e145..2422e051e 100644--- a/docs/FAQ.md+++ b/docs/FAQ.md@@ -125,8 +125,53 @@ http the password crosses your network unencrypted, so keep that to a network yo### Can I use a password instead of a passkey?-Yes, if the instance allows it: set `PASSWORD_LOGIN=1`. It's off by default. See-[password sign-in](SELF_HOSTING.md#password-sign-in-optional).+Yes, if the instance allows it. It's off by default; put `PASSWORD_LOGIN=1` in `.env` and run+`docker compose up -d` (a `restart` keeps the old settings). Then:++- The sign-in screen offers **Sign in with password**: your profile name (or a sign-in e-mail, if+ you added one) and the password. **Create new profile** can use a password instead of a passkey.+- A profile made with a passkey gets a password under **Settings → Account → Password**,+ confirmed with that passkey once. Nobody has a password until they set one.+- Forgot it? There is no reset mail, because openGym never sends mail. An admin opens you in the+ admin dashboard and picks **Reset password**, which gives a one-time code for **Sign in with+ password → Have a reset code?**.+- Wrong passwords are slowed down per name and per address. Running the API behind a proxy of+ your own instead of the bundled `web` container? Read the `TRUST_PROXY` note in+ `.env.example` first.+- Switching it off again turns every password off at once. Profiles that only have a password are+ locked out until it comes back, so have them add a passkey first.++Passkeys stay the safer choice, and over plain http a password crosses your network in the clear.+The details are in [password sign-in](SELF_HOSTING.md#password-sign-in-optional).++### What is guest mode, and can I turn it off?++**Continue without account** on the sign-in screen is guest mode. Everything stays in that+browser: no profile, no sync, nothing on the server, and the admin dashboard never sees it. Handy+for a quick look. Create a profile later on the same device and your guest data moves into it.++On an instance for a known set of people, set `ALLOW_GUEST=0` in `.env` and `docker compose up -d`.+The button disappears and a profile becomes the only way in. Anyone already in as a guest is sent+to the sign-in screen on their next visit; their data stays in their browser and isn't deleted.+`INVITE_ONLY=1` is the other half: it decides who may create a profile, and doesn't touch guests.++Ended up a guest without meaning to? If signing in never works and only **Continue without+account** does, the browser can't reach the API. Check that the `api` container runs next to+`web` (a NAS stack with only `web` does exactly this) and see+[On a NAS](SELF_HOSTING.md#on-a-nas-synology-qnap-unraid-truenas).++### Can I run it on my NAS?++Yes: Synology, QNAP, Unraid and TrueNAS all run the two containers. Use absolute paths for+`data/` and `env_file`, set `ORIGIN` to the exact address you open, and put the NAS's reverse+proxy in front for HTTPS. The walkthrough, with a compose file to paste, is in+[On a NAS](SELF_HOSTING.md#on-a-nas-synology-qnap-unraid-truenas).++### The app says "This server only takes changes made at ...".++The server's `ORIGIN` isn't the address in your browser, so it refuses every save as if it came+from another site. `docker compose logs api` shows a `refused cross-origin` line that names the+`ORIGIN=` and `RP_ID=` to put in `.env`. Set them, `docker compose up -d`, reload.### Can several people use one instance?diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.mdindex c445d2fa8..c009c1c61 100644--- a/docs/SELF_HOSTING.md+++ b/docs/SELF_HOSTING.md@@ -9,7 +9,7 @@ This guide takes you from "just cloned it" to "using it from my phone over the i2. [The passkey requirement](#2-understand-the-passkey-requirement-important) — why your phone needs HTTPS3. [HTTPS on your own domain](#3-expose-it-over-https-on-your-own-domain) — Cloudflare Tunnel, Caddy, Traefik, nginx, Tailscale Serve4. [Multiple users](#4-multiple-users) — admin dashboard, invites, language, activity log, password sign-in-5. [Fitting into an existing stack](#5-fitting-it-into-an-existing-stack) — ports, subpaths, media uploads+5. [Fitting into an existing stack](#5-fitting-it-into-an-existing-stack) — ports, [NAS](#on-a-nas-synology-qnap-unraid-truenas), subpaths, media uploads6. [Backups](#6-backups)7. [Notifications](#7-notifications)8. [Updating](#8-updating)@@ -522,6 +522,84 @@ Note the difference from `VITE_IMG_BASE` / `VITE_GIF_BASE` (see Troubleshooting)build-time values baked into the frontend bundle, and setting them next to `docker compose` doesnothing to an image you pulled.+### On a NAS (Synology, QNAP, Unraid, TrueNAS)++A NAS runs openGym like any other Docker host. What trips people up is the NAS's own compose UI,+which is not quite `docker compose` in a folder you chose. Four things to get right:++**1. Both services, every time.** openGym is `api` *and* `web`. A stack with only `web` still+loads, but every sign-in fails and the only way in that works is **Continue without account**:+you are a guest, your data lives in that one browser, and nothing reaches the NAS. If the+sign-in screen never accepts anything, check that `docker ps` shows both containers.++**2. Absolute paths.** Container Station, Container Manager and Portainer keep the compose file+in a folder of their own, so `./data` and `env_file: .env` resolve somewhere you did not put+them. Spell them out (here for QNAP; use your share's path):++```yaml+name: opengym+services:+ api:+ image: ghcr.io/duartesantos8/opengym-api:latest+ restart: unless-stopped+ env_file: /share/Container/opengym/.env+ environment:+ - PORT=3000+ - DATA_DIR=/data+ - TRUST_PROXY=1+ volumes:+ - /share/Container/opengym/data:/data+ web:+ image: ghcr.io/duartesantos8/opengym-web:latest+ restart: unless-stopped+ depends_on: [api]+ ports:+ - "3030:80"+ environment:+ - BACKEND=api+ - PORT=3000+```++Typical roots: Synology `/volume1/docker/opengym`, QNAP `/share/Container/opengym`, Unraid+`/mnt/user/appdata/opengym`, TrueNAS SCALE a dataset such as `/mnt/tank/apps/opengym`. Create the+`data` folder and the `.env` file there first. On TrueNAS SCALE 24.10 and later this file goes in+**Apps → Discover Apps → ⋮ → Install via YAML**; on Synology in **Container Manager →+Project → Create**; on Unraid in the Compose Manager plugin. Unraid's single-container templates+can work too, as long as both containers share one custom network and `BACKEND` names the API+container.++**3. ORIGIN is the address you type.** Pick the port on the left of `ports:` (`3030` above, any+free one: DSM itself sits on 5000/5001, QNAP's on 8080) and put the exact address in `.env`:++```env+ORIGIN=http://10.11.0.4:3030+RP_ID=10.11.0.4+```++Get this wrong and every save is refused. The app says "This server only takes changes made+at ...", and `docker compose logs api` prints a `refused cross-origin` line with the `ORIGIN=`+and `RP_ID=` to set. After changing `.env`, recreate the stack (Container Station's **Recreate**,+Container Manager's **Build**, or `docker compose up -d`); a plain restart keeps the old values.+Over plain http on a LAN address there are no passkeys (see [§2](#2-understand-the-passkey-requirement-important)),+so for a first look either add `PASSWORD_LOGIN=1` ([password sign-in](#password-sign-in-optional))+or keep going to step 4.++**4. HTTPS through the NAS's reverse proxy.** For passkeys, the iPhone web app and+notifications, give openGym a hostname with a certificate and point the proxy at the `web`+port: Synology **Control Panel → Login Portal → Advanced → Reverse Proxy** (certificate under+**Security → Certificate**), QNAP **Network & File Services → Network Access → Reverse Proxy**,+Unraid and TrueNAS with Nginx Proxy Manager, Caddy or SWAG, or a Cloudflare Tunnel or Tailscale+Serve from [§3](#3-expose-it-over-https-on-your-own-domain). Then `ORIGIN` and `RP_ID` become that+hostname, and the LAN address stops being a way in.++**Permissions.** The `api` container runs as root and writes everything under `data/`; its+`secret`, `db.json` and `coach.json` end up root-owned with mode 600. A share mounted over NFS+with root squash, or a TrueNAS dataset whose ACL maps root away, refuses those writes, and the+API log says `EACCES` or `EPERM`. Give the dataset to root, or run `api` with `user: "568:568"`+(TrueNAS's `apps` user, say) and make `data/` that user's first. Coach providers with an API key+work either way; only the in-container CLI runtimes (`API_TARGET=coach`) need root. Your backup+job reads `data/` as root, or as that user.+### Serving openGym under a subpathopenGym can live at `https://example.com/gym/` rather than on a host of its own. Which of the two@@ -948,6 +1026,8 @@ browser (see section 2).| Symptom | Fix ||---|---|| No passkey prompt on my phone | You're on `http://` or an IP, not HTTPS. Set up a domain (section 3). |+| "This server only takes changes made at ...", or `refused cross-origin` in the API log | `ORIGIN` is not the address in your browser. The log line names the `ORIGIN=` and `RP_ID=` to set; then `docker compose up -d`. See [On a NAS](#on-a-nas-synology-qnap-unraid-truenas). |+| The sign-in screen accepts nothing, only "Continue without account" works | The `api` service is not running or `web` cannot reach it (`BACKEND`, `PORT`). Without it you are a guest and nothing is saved on the server. || "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. || Exercise pictures missing | You are on an image older than v1.4.0 or a custom build: `docker compose pull && docker compose up -d`. A source build needs `catalogue/media/` checked out. || Port 8080 already used | Set `WEB_PORT=9090` in `.env` (and update `ORIGIN` for local testing). |diff --git a/website/docs.html b/website/docs.htmlindex 1f813648a..9902ef4e2 100644--- a/website/docs.html+++ b/website/docs.html@@ -118,6 +118,7 @@<a class="side-sub" href="#sh-https">HTTPS on your domain</a><a class="side-sub" href="#sh-notify">Notifications</a><a class="side-sub" href="#sh-stack">In an existing stack</a>+ <a class="side-sub" href="#sh-nas">On a NAS</a><a class="side-sub" href="#sh-update">Updating</a></div></div>@@ -617,6 +618,21 @@ ORIGIN=https://example.com # no /gym here</code></pre>sign up and still not be signed in. Both setups are in<a href="https://github.com/DuarteSantos8/openGym/blob/main/docs/SELF_HOSTING.md#nginx-under-gym-both-ways" rel="noopener">SELF_HOSTING.md</a>.</p>+ <h3 id="sh-nas">On a NAS (Synology, QNAP, Unraid, TrueNAS)</h3>+ <p>Works like any Docker host, with four catches. <b>Run both services</b>: a stack with only+ <code>web</code> loads, but sign-in never works and <b>Continue without account</b> quietly+ makes you a guest whose data stays in that browser. <b>Use absolute paths</b> for the data+ volume and <code>env_file</code> (for example <code>/share/Container/opengym/.env</code>), because+ the NAS's compose UI keeps the file in a folder of its own. <b>Set <code>ORIGIN</code> to the+ exact address you type</b>, port included (<code>ORIGIN=http://10.11.0.4:3030</code>,+ <code>RP_ID=10.11.0.4</code>), then recreate the stack; otherwise every save is refused and the+ API log's <code>refused cross-origin</code> line names the values to set. <b>Add HTTPS</b>+ through the NAS's reverse proxy (Synology Login Portal, QNAP Reverse Proxy, Nginx Proxy+ Manager or Caddy on Unraid and TrueNAS) for passkeys. The <code>api</code> container runs as+ root and writes <code>data/</code>, so an NFS share with root squash needs a different owner.+ The full walkthrough with a compose file to paste is in+ <a href="https://github.com/DuarteSantos8/openGym/blob/main/docs/SELF_HOSTING.md#on-a-nas-synology-qnap-unraid-truenas" rel="noopener">SELF_HOSTING.md</a>.</p>+<h3 id="sh-update">Updating</h3><pre><code>git pull # picks up compose/config changesdocker compose pull # (or: docker compose up -d --build, if building from source)@@ -998,6 +1014,8 @@ Leg Day,Leg Press,2026-08-21,200,1</code></pre><h3 id="tr-rest">Everything else</h3><table class="cfg"><tr><td>No passkey prompt on my phone</td><td>You're on <code>http://</code> or a bare IP. Passkeys need HTTPS or localhost — set up a domain, or use guest mode / the mobile app.</td></tr>+ <tr><td>"This server only takes changes made at ..."</td><td><code>ORIGIN</code> isn't the address in your browser. <code>docker compose logs api</code> shows a <code>refused cross-origin</code> line naming the <code>ORIGIN=</code> and <code>RP_ID=</code> to set; then <code>docker compose up -d</code>.</td></tr>+ <tr><td>Sign-in never works, only "Continue without account"</td><td>The <code>api</code> container isn't running or <code>web</code> can't reach it (<code>BACKEND</code>, <code>PORT</code>). As a guest nothing is saved on the server.</td></tr><tr><td>"verification failed" on login</td><td><code>RP_ID</code>/<code>ORIGIN</code> don't match the address bar — see the checklist above, starting with what the server logged.</td></tr><tr><td>Exercise pictures missing</td><td>You're on an image older than v1.4.0 or a custom build: <code>docker compose pull && docker compose up -d</code>. A source build needs <code>catalogue/media/</code> checked out.</td></tr><tr><td>Port 8080 already used</td><td><code>WEB_PORT=9090</code> in <code>.env</code> (and update <code>ORIGIN</code> for local testing).</td></tr>@@ -1068,6 +1086,19 @@ Leg Day,Leg Press,2026-08-21,200,1</code></pre>QR code, a password manager, a security key or a Windows Hello PIN. Or switch on passwordswith <code>PASSWORD_LOGIN=1</code> in <code>.env</code> and <code>docker compose up -d</code>:the sign-in screen then offers <b>Sign in with password</b> and new profiles can use one.</p>+ <h3>Can I use a password instead of a passkey?</h3>+ <p>Yes, if the instance allows it: <code>PASSWORD_LOGIN=1</code> in <code>.env</code>, then+ <code>docker compose up -d</code>. Off by default. The sign-in screen gets <b>Sign in with+ password</b> (profile name or sign-in e-mail), new profiles can use one, and a passkey profile+ adds one under <b>Settings → Account → Password</b>. openGym never sends mail, so a forgotten+ password is reset with a one-time code from the admin dashboard. Switching it off later locks+ out profiles that only have a password. <a href="#admin-signin">More on signing in</a>.</p>+ <h3>What is guest mode, and can I turn it off?</h3>+ <p><b>Continue without account</b> keeps everything in that browser: no profile, no sync,+ nothing on the server. Make a profile on the same device later and the data moves in. For an+ instance meant for a known set of people, <code>ALLOW_GUEST=0</code> removes the button;+ <code>INVITE_ONLY=1</code> decides who may create a profile. Stuck as a guest because sign-in+ never works? The <code>api</code> container isn't reachable (<a href="#sh-nas">NAS notes</a>).</p><h3>The AI Coach doesn't show up on my server.</h3><p>Nothing in <code>.env</code> switches it on; an admin does, in the app. If Settings →Account has no <b>Admin dashboard</b>, nobody is admin yet: copy <b>Settings → Account →