openGym zelf hosten met Docker Compose: handleiding
Leer hoe u openGym op een VPS implementeert. Wij behandelen het vastzetten van de git tag v1.2.7, het configureren van TLS voor passkeys en het beheren van lokale JSON-data.
Wat u krijgt wanneer u openGym zelf host
U host openGym zelf door de repository te klonen, twee regels in .env aan te passen en docker compose up -d --build uit te voeren achter een reverse proxy die TLS (transport layer security) afhandelt. openGym is een tracker voor fitness en lichaamsgewicht: wekelijkse schema's, begeleide trainingen, elke set gelogd en gewicht over tijd. Het is gelicentieerd onder AGPL-3.0 en slaat alles op in eenvoudige JSON-bestanden op uw schijf, waardoor er geen databaseserver nodig is.
De stack bestaat uit twee langlopende containers: een nginx-container die de React-build serveert en een Node-container die de API bevat, plus een eenmalige taak die bij de eerste start ongeveer 140 MB aan oefeningsafbeeldingen en GIF's downloadt.
Twee zaken die de README van het project impliceert, maar niet expliciet benoemt voor iemand die op een publieke server implementeert. Passkey-login is gebonden aan een hostnaam, dus het domein en het bijbehorende certificaat moeten bestaan vóór de eerste login, niet daarna. En de optionele MCP-server is alleen-lezen in de vastgezette v1.2.7-tag en draait op de machine waar uw AI-client draait, niet binnen de stack; dit verandert uw werkwijze wanneer de data op een VPS staat. De huidige MCP-server ondersteunt ook het loggen van trainingen na koppeling met uw server.
openGym is nog jong. De eerste getagde release, v1.0.0, dateert van 20 juli 2026 en v1.2.7 verscheen op 18 augustus 2026. Dertien tags in de eerste maand en 34 op 9 oktober 2026, met v1.4.0 die op die dag werd getagd, betekent dat de applicatie nog volop in ontwikkeling is. Check daarom een release-tag uit in plaats van de build van de standaard branch te gebruiken.
Plan het domein vóór de eerste aanmelding
Passkeys zijn de manier waarop u zich aanmeldt bij openGym. Een passkey is gekoppeld aan een relying party ID (RP ID), wat het domein is waarop de credential is aangemaakt. Browsers maken passkeys uitsluitend aan via HTTPS. De enige uitzondering is localhost.
Dit heeft een consequentie waar gebruikers op hun telefoon tegenaan lopen. Open http://203.0.113.10:8080 vanaf een ander apparaat en er verschijnt helemaal geen prompt voor een passkey, omdat de browser weigert een credential aan te maken op een HTTP-oorsprong of een kaal IP-adres. De eigen probleemoplossingsnotities van het project vermelden hetzelfde: geen prompt betekent dat u zich op http:// bevindt of op een IP-adres.
Erger nog, het RP ID is verankerd in elke credential die uw gebruikers al hebben geregistreerd. Wijzig RP_ID op een later moment en de passkeys die op hun apparaten zijn opgeslagen, komen niet langer overeen, waardoor niemand zich meer kan aanmelden. Bepaal eerst de hostnaam, wijs DNS naar de VPS en zorg dat het certificaat werkt voordat iemand op Create profile tikt.
openGym implementeren met Docker Compose
Het compose-bestand maakt bind-mounts van ./data en ./media relatief aan zichzelf, waardoor de map waarin u kloont uw database is. Plaats deze op een duurzame locatie.
sudo install -d -o "$USER" -g "$USER" /opt/opengym
git clone https://github.com/DuarteSantos8/openGym /opt/opengym
cd /opt/opengym
git checkout v1.2.7
cp .env.example .envDe README toont een github.com/DuarteSantos8/openGym clone-URL. Sinds 4 november 2026 is die repository bereikbaar en wordt deze beschreven als de thuisbasis van het project. Check de tag uit vóór de eerste build: de standaard branch is verder gevorderd dan de versie die in deze handleiding wordt beschreven. In die nieuwere versie zitten de animaties voor de oefeningen in de image en bestaat de onderstaande media-job niet meer. De sectie over pinning legt uit waarom dit belangrijk is.
Bewerk .env. Op een VPS zijn drie regels van belang.
RP_ID=gym.example.com
ORIGIN=https://gym.example.com
WEB_PORT=127.0.0.1:8080RP_ID is de kale hostnaam en ORIGIN is de volledige URL inclusief het schema. Deze moeten exact overeenkomen met de adresbalk, anders mislukt het inloggen met verification failed. De waarde WEB_PORT wordt toegelicht in de sectie over het privé houden van poort 8080.
docker compose up -d --build
docker compose ps --all
docker compose logs mediadocker compose ps --all hoort web en api als actief te tonen, en media als afgesloten met code 0. Gebruik de vlag --all: zonder deze vlag toont Compose alleen actieve containers, waardoor de voltooide media-job niet zichtbaar is. Deze afsluiting is correct: de media-job heeft restart: "no" omdat de taak een eenmalige download is. Het logbestand eindigt met een regel die begint met ✓ Exercise media ready, en ls media/img | wc -l hoort 1.324 te tonen in plaats van 0. Dit is het aantal thumbnails dat de upstream-dataset voor oefeningen bevat sinds 9 oktober 2026. Een lege map betekent dat de download is mislukt, waarna de applicatie de oefenkaarten met lege afbeeldingen rendert.
Gebruik de vlag --build. Het compose-bestand bij deze tag benoemt vooraf gebouwde images op ghcr.io met de tag latest. Deze images zijn sinds 18 oktober 2026 opnieuw gepubliceerd, maar latest volgt de nieuwste release, waardoor docker compose pull nieuwere code zou draaien dan de broncode die u zojuist heeft uitgecheckt. Beide services bevatten een build-sectie, en --build bouwt ze op basis van uw checkout. Als Compose nieuw voor u is, begin dan bij Docker Compose op een VPS en keer daarna terug.
Zet de versie vast, aangezien dit project nog jong is
De registry bevat weer versies van images, maar het compose-bestand in v1.2.7 vraagt nog steeds om latest. Sinds 4 november 2026 wijst latest naar 1.4.4, uitgebracht op 3 november 2026. Wat u vastzet is de checkout op schijf, aangezien deze bepaalt welke versie van de applicatie in de container terechtkomt.
cd /opt/opengym
git fetch --tags
git checkout v1.2.7git status rapporteert nu een detached HEAD bij die tag, wat precies is wat u op een server wilt. Er verandert niets onder uw handen totdat u een andere versie uitcheckt.
v1.2.7 is de release waarvoor deze handleiding is geschreven, en het is niet langer de nieuwste. Latere releases wijzigen de deployment zelf (op de standaard branch is de media-job verdwenen), dus lees de release notes en vergelijk het compose-bestand voordat u de versie wijzigt. De release notes van v1.4.2 en v1.4.3 vermelden ook beveiligingsoplossingen, en het project verzoekt self-hosters om bij te werken.
Instrueer Compose vervolgens om de registry helemaal niet meer te benaderen. Plaats dit in docker-compose.override.yml, dat Compose automatisch laadt en samenvoegt met het gevolgde bestand. Scalaire sleutels worden vervangen door de override, waardoor er niets in git bewerkt hoeft te worden en git pull schoon blijft. Zie hoe Compose een override-bestand samenvoegt voor de volledige samenvoegregels.
services:
api:
pull_policy: build
web:
pull_policy: buildZodra dit is ingesteld, bouwt een latere docker compose up -d vanuit de broncode die u heeft, in plaats van de versie op te halen waar latest op die dag naar wijst. Controleer of de samenvoeging effect heeft gehad en herbouw vervolgens op de tag.
docker compose config | grep pull_policy
docker compose up -d --buildTLS-termination met een reverse proxy
De containers communiceren via standaard HTTP. Een component aan de voorzijde moet het certificaat beheren. Caddy is de snelste methode, omdat deze automatisch certificaten aanvraagt en vernieuwt bij Let's Encrypt.
gym.example.com {
reverse_proxy 127.0.0.1:8080
}nginx, Traefik en Nginx Proxy Manager werken op dezelfde wijze. Dit geldt ook voor een Cloudflare Tunnel, die in de projectdocumentatie wordt beschreven en waarvoor geen inkomende poorten hoeven te worden geopend.
curl -sI https://gym.example.com | head -1Dit zou HTTP/2 200 moeten retourneren zonder certificaatwaarschuwing. Open nu de site in een browser en tik op Create profile. Als de passkey-prompt verschijnt en de login vervolgens verification failed rapporteert, komt RP_ID of ORIGIN niet overeen met de URL in de adresbalk. Corrigeer .env en voer docker compose up -d opnieuw uit; hiermee worden de containers opnieuw aangemaakt zodat ze de nieuwe waarden inlezen. Een docker compose restart herlaadt .env niet.
Houd poort 8080 buiten het publieke internet
Standaard publiceert de webservice 8080 op elke interface. Hierdoor is de applicatie bereikbaar via onversleuteld HTTP op uw publieke IP-adres, terwijl de proxy HTTPS op dezelfde machine afhandelt. Een firewallregel lost dit niet op. Docker publiceert een poort met een DNAT-regel in de nat-tabel. Dat verkeer wordt vervolgens afgehandeld in de FORWARD-chain, waar de eigen regels van Docker het accepteren, terwijl de regels van ufw zich op het INPUT-pad bevinden. sudo ufw deny 8080/tcp blokkeert daarom niets.
De oplossing is om alleen op het loopback-adres te publiceren. Het compose-bestand mapt "${WEB_PORT:-8080}:${NGINX_PORT:-80}", dus alles wat u instelt in WEB_PORT wordt vervangen aan de linkerzijde van die mapping. De korte syntaxis van Docker accepteert daar een ip:port-paar. Daarom werkt WEB_PORT=127.0.0.1:8080.
docker compose config
sudo ss -ltnp | grep 8080In de samengevoegde configuratie, onder de ports van de webservice, wilt u host_ip: 127.0.0.1 zien. ss zou 127.0.0.1:8080 moeten tonen en niet 0.0.0.0:8080. Vanaf een andere machine zou curl http://<your-vps-ip>:8080 nu geweigerd moeten worden of een time-out moeten geven, terwijl de HTTPS-hostnaam blijft werken.
Registratie sluiten zodra uw profiel bestaat
Registratie staat standaard open en de gastmodus is ingeschakeld. Op een publieke hostnaam betekent dit dat iedereen die de URL vindt, een profiel op uw server kan aanmaken. Registreer eerst uw eigen profiel en zoek vervolgens uw gebruikers-ID op: ls data/ toont een bestand genaamd state-<uid>.json voor elke gebruiker, en die <uid> is de waarde die u nodig heeft.
ADMIN_UIDS=<your-uid>
INVITE_ONLY=1
ALLOW_GUEST=0Voer docker compose up -d opnieuw uit. Bij de instellingen verschijnt nu een beheerdersdashboard waar u uitnodigingscodes kunt genereren en intrekken, zodat alleen de mensen met wie u traint zich kunnen registreren. openGym ondersteunt geen externe identiteitsproviders; deze uitnodigingscodes beheren dus uitsluitend deze applicatie en niets anders op de server. Als u liever één account per persoon gebruikt voor alle services die u draait, kunt u Authentik als forward auth proxy voor de applicatie plaatsen. Dit beveiligt de hostnaam voordat het eigen passkey-inlogscherm van openGym wordt geladen.
Waar de data zich bevindt en de back-up die deze beschermt
Alles staat in de map ./data, die in de API-container is gemount op /data. Er zijn vier soorten bestanden: db.json bevat profielen en publieke passkey-gegevens, state-<uid>.json bevat de routines, workouts en het lichaamsgewicht van één gebruiker, secret is de sleutel voor sessiecookies, en vapid.json bevat de push-notificatiesleutels die bij de eerste uitvoering worden gegenereerd.
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start apiStop eerst de API zodat de bestanden consistent met elkaar blijven terwijl tar ze kopieert. Vanaf v1.2.7 schrijft de API database- en workout-status-JSON naar een tijdelijk bestand en hernoemt dit atomair naar de doelbestemming, waardoor deze actieve bestanden niet op hun plek worden overschreven. Kopieer het archief vervolgens van de server, want een archief dat op de VPS blijft staan, overleeft het verlies van de VPS niet. Laat media/ buiten de back-up: dit is 140 MB aan oefeningsafbeeldingen die de media-job kosteloos opnieuw downloadt.
Herstellen betekent het uitpakken van het archief naar hetzelfde pad op een host die hetzelfde domein bedient. Een passkey die op uw telefoon is opgeslagen, is gekoppeld aan de RP ID waarvoor deze is aangemaakt. Een herstel naar een nieuwe hostnaam levert dus een werkende database op waar niemand op kan inloggen. Behoud het domein, of houd er rekening mee dat u elke passkey opnieuw moet registreren. Dezelfde discipline geldt voor alles wat u draait, en het maken van back-ups en upgraden van een Docker Compose stack behandelt de algemene procedure.
De vastgezette MCP-server is alleen-lezen en draait op uw machine
MCP (model context protocol) is de manier waarop een client zoals Claude Desktop of Cursor communiceert met een lokale toolserver. openGym levert er een mee in mcp/. Deze maakt geen deel uit van het compose-bestand, is geen container en luistert op geen enkele poort. De client start de server als een onderliggend proces en communiceert via stdio. De vastgezette server leest alleen lokale bestanden; de huidige server verstuurt daarnaast trainingsgegevens naar uw gekoppelde openGym API.
Installeer deze waar de client draait, niet op de server:
cd openGym/mcp
npm installVoeg deze vervolgens toe aan claude_desktop_config.json:
{
"mcpServers": {
"opengym": {
"command": "node",
"args": ["/absolute/path/to/openGym/mcp/src/index.js"],
"env": {
"OPENGYM_DATA": "/absolute/path/to/openGym/data",
"OPENGYM_UID": "<your-uid>"
}
}
}
}OPENGYM_UID is optioneel bij een installatie voor één gebruiker, waarbij de server het enige gevonden profiel detecteert. Op de huidige standaard branch stelt deze elf tools beschikbaar: list_routines, get_routine, preview_session, get_week_plan, list_workouts, get_workout, get_bodyweight, estimate_1rm, muscle_balance, get_programme en log_workout. preview_session toont wat de app daadwerkelijk op het scherm zal tonen wanneer u een routine start, nadat het progressiebeleid en uw geschiedenis het plan hebben overschreven. De v1.2.7-tag bevatte acht alleen-lezen tools, zonder preview_session, get_programme of log_workout. Een assistent die die vastgezette server gebruikt, kan beantwoorden wat u vorige week hebt gebankt, maar kan geen set loggen, een routine bewerken of iets verwijderen. Op de huidige branch lezen tien tools gegevens en slaat log_workout trainingen op via uw server na koppeling; dit is uitgeschakeld totdat de koppeling is voltooid. Die lijst is een compact voorbeeld van de beslissing waar het ontwerp van agents steeds op terugkomt: de tools die u beschikbaar stelt, vormen het volledige bereik van wat een model kan doen, en leren hoe agents werken door zelf de loop te schrijven is de snelste manier om in te zien waarom een alleen-lezen toolset een ontwerpkeuze is in plaats van een beperking.
Dit is het onderdeel dat een VPS-gebruiker moet oplossen. OPENGYM_DATA is een bestandssysteempad en uw gegevens staan op de VPS, terwijl uw AI-client op uw laptop staat. Twee opties die hier eerlijk over zijn.
- Kopieer de gegevens naar uw lokale machine en laat de server naar de kopie wijzen:
rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/, en stel vervolgensOPENGYM_DATAin op~/opengym-data. De vastgezette server leest alleen, dus een kopie verliest niets. Voer de rsync opnieuw uit wanneer u actuele cijfers wilt. - Draai de server via ssh, met
commandingesteld opsshenargsingesteld op["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Hiervoor moet Node op de VPS zijn geïnstalleerd en is een login vereist die niets naar stdout schrijft, omdat stdout het protocolkanaal is.
Beide opties gaan ervan uit dat de agent zelf op uw laptop leeft. Als u wilt dat deze op dezelfde machine draait als de gegevens, geeft OneCLI elke persoon een gesandboxte agent op de server, zodat de stdio-hop terug naar data/ weer een lokale hop is.
Als cat data/db.json de waarde Permission denied retourneert, heeft de API-container die bestanden als root geschreven en kan uw login ze niet lezen. Kopieer ze met sudo of wijzig het eigenaarschap op de host. Voor servers die bedoeld zijn om via het netwerk te luisteren in plaats van via stdio, zie MCP-servers draaien op een VPS.
openGym of wger: welke moet u draaien?
wger is de gevestigde optie in deze niche en het is een aanzienlijk groter softwarepakket. De compose-stack draait gunicorn voor een Django-applicatie, PostgreSQL, Redis en een Celery-worker achter nginx. In ruil daarvoor krijgt u tracking voor voeding en ingrediënten, een gedocumenteerde REST API, een grote database met oefeningen van de community en functies voor trainers die de schema's van anderen beheren.
openGym bestaat uit twee containers, een map met JSON-bestanden en geen accounts om te beheren, behalve passkeys. Dat is het volledige verschil. Als u ooit een Chatwoot-installatie draaiende heeft gehouden, waarbij een back-up een Postgres-dump naast de uploads-map betekent en elke versie-update database-migraties vereist, dan weet u al wat het onderhoud van wger van u vraagt.
Draai wger als u naast uw training ook voeding wilt bijhouden, of als u een API nodig heeft om op te bouwen. Draai openGym als u een stack wilt die klein genoeg is om in een middag van begin tot eind door te lezen, en een login zonder wachtwoord dat kan lekken. De prijs voor die keuze is volwassenheid: op 19 augustus 2026 is de eerste release van openGym een maand oud, terwijl wger jaren aan releases achter de rug heeft. Pin uw versie, maak back-ups en lees de release notes voor elke update.
Als u nog beslist wat een plek op de server verdient, behandelt wat is de moeite waard om zelf te hosten in 2026 de afwegingen, en deze app past uitstekend naast Mealie voor recepten of Actual Budget voor financiën op dezelfde kleine VPS.
Updaten zonder gegevensverlies
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api
git fetch --tagsCheck de gewenste release uit met git checkout v<new> en voer vervolgens docker compose up -d --build uit, zodat de containers opnieuw worden opgebouwd op basis van die tag. Maak altijd eerst een back-up, aangezien het herstellen van JSON-bestanden op schijf slechts één tar-commando vereist en enkele seconden in beslag neemt.
FAQ
Waarom toont openGym nooit een passkey-prompt op mijn telefoon?
De browser weigert een credential aan te maken omdat u zich op http:// bevindt of op een kaal IP-adres, zoals http://192.168.1.20:8080. Browsers staan passkeys alleen toe op HTTPS-origins, met localhost als enige uitzondering. Plaats openGym achter een reverse proxy die een geldig certificaat voor een echte hostnaam beheert, stel RP_ID=gym.example.com en ORIGIN=https://gym.example.com in .env in, en voer docker compose up -d uit zodat de containers de nieuwe waarden overnemen. Als de prompt verschijnt maar de login meldt verification failed, dan komen die twee waarden niet exact overeen met de URL in de adresbalk.
Waar slaat openGym mijn gegevens op en hoe maak ik een back-up?
In de map ./data naast het compose-bestand, die als /data in de API-container is gemount. Deze bevat db.json voor profielen en publieke passkey-credentials, één state-<uid>.json per gebruiker voor trainingen en lichaamsgewicht, secret voor de sessie-cookie-sleutel, en vapid.json voor push-notificatiesleutels. Maak een back-up met docker compose stop api, vervolgens tar czf ~/opengym-$(date +%F).tar.gz data/, daarna docker compose start api, en kopieer het archief van de server af. Sla media/ over; dit is 140 MB aan oefeningsafbeeldingen die de media-job zelf opnieuw downloadt.
Kan Claude mijn openGym-trainingsgeschiedenis lezen?
Ja, via de optionele MCP-server in de map mcp/. De vastgezette v1.2.7-server heeft acht read-only tools. De huidige default-branch heeft elf tools: tien leesroutines, sessievoorbeelden, weekplannen, trainingen, lichaamsgewicht, geschatte one-rep max, spierbalans en programma's; log_workout schrijft trainingen via uw server na het koppelen. Het is geen container en opent geen poort: uw client start het via stdio en de lees-tools benaderen de JSON-bestanden op OPENGYM_DATA direct. Omdat dit een bestandssysteempad is, betekent het draaien van openGym op een VPS dat u ofwel een kopie van data/ synchroniseert naar de machine waarop de client draait, of de server aanroept via ssh vanuit de client-configuratie.
Moet ik openGym of wger zelf hosten?
Kies wger als u naast uw trainingslogboek ook voeding wilt bijhouden, of als u een gedocumenteerde REST API nodig heeft om op voort te bouwen. Het draait een grotere stack: Django onder gunicorn, PostgreSQL, Redis en een Celery-worker achter nginx. Kies openGym als u twee containers wilt, JSON-bestanden die u kunt lezen met cat, en passkey-login zonder wachtwoordbeheer. Sinds 19 augustus 2026 is de eerste tagged release van openGym één maand oud; check daarom een git-tag uit en maak een back-up van data/ vóór elke update.