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.

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.md
index 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 (than
browser, the app now says which address the server expects and what to change, instead of a
bare "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.md
index 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.md
index 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 i
2. [The passkey requirement](#2-understand-the-passkey-requirement-important) — why your phone needs HTTPS
3. [HTTPS on your own domain](#3-expose-it-over-https-on-your-own-domain) — Cloudflare Tunnel, Caddy, Traefik, nginx, Tailscale Serve
4. [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 uploads
6. [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` does
nothing 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 subpath
openGym 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.html
index 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 changes
docker 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 &amp;&amp; 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 passwords
with <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 →