SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor · Mis à jour le 2026-11-06

Auto-héberger openGym avec Docker Compose

Déployez openGym sur un VPS avec Docker Compose : tag Git figé, TLS avant la première passkey, données en JSON et serveur MCP optionnel.

Ce que vous obtenez en auto-hébergeant openGym

Vous auto-hébergez openGym en clonant le dépôt, en modifiant deux lignes dans .env, puis en exécutant docker compose up -d --build derrière un reverse proxy qui termine le TLS (Transport Layer Security). openGym est une application de suivi de la pratique sportive et du poids corporel : programmes hebdomadaires, entraînements guidés, journalisation de chaque série et suivi du poids au fil du temps. Elle est distribuée sous licence AGPL-3.0 et stocke toutes les données dans des fichiers JSON en clair sur votre disque. Aucun serveur de base de données n’est donc nécessaire.

La stack se compose de deux conteneurs qui s’exécutent en continu : un conteneur nginx qui sert le build React et un conteneur Node qui héberge l’API. Elle comprend également un job ponctuel qui télécharge environ 140 MB d’images et de GIF d’exercices lors du premier démarrage.

Deux points sont sous-entendus par le README du projet, mais ne sont pas détaillés pour un déploiement sur un serveur public. La connexion par passkey est liée à un hostname. Le domaine et son certificat doivent donc être disponibles avant la première connexion, et non après. Le serveur MCP facultatif est en lecture seule avec le tag v1.2.7 épinglé. Il s’exécute sur la machine où votre client IA fonctionne, et non à l’intérieur de la stack. Cela modifie les opérations à effectuer lorsque les données se trouvent sur un VPS. Le serveur MCP actuel prend également en charge la journalisation des entraînements après association avec votre serveur.

openGym est récent. La première release taguée, v1.0.0, date du 20 July 2026, et v1.2.7 a été publiée le 18 August 2026. Treize tags au cours de son premier mois, puis 34 au 9 October 2026, avec v1.4.0 tagué ce jour-là : l’application évolue encore rapidement. Consultez donc un tag de release au lieu de construire ce qui se trouve sur la branche par défaut.

Planifiez le domaine avant la première connexion

Les passkeys servent à vous connecter à openGym. Une passkey est liée à un relying party ID (RP ID), c’est-à-dire au domaine sur lequel l’identifiant a été créé. Les navigateurs ne créent des passkeys qu’en HTTPS. La seule exception est localhost.

Cela a une conséquence que l’on rencontre sur téléphone. Ouvrez http://203.0.113.10:8080 depuis un autre appareil : aucune demande de création de passkey n’apparaît, car le navigateur refuse de créer un identifiant sur une origine HTTP simple ou sur une adresse IP seule. Les notes de dépannage du projet indiquent la même chose : l’absence de demande signifie que vous utilisez http:// ou une adresse IP.

Le RP ID est en outre intégré à chaque identifiant que vos utilisateurs ont déjà enregistré. Si vous modifiez RP_ID par la suite, les passkeys stockées sur leurs appareils ne correspondent plus et personne ne peut se connecter. Choisissez d’abord le nom d’hôte, faites pointer le DNS vers le VPS et configurez le certificat avant que quiconque appuie sur Create profile.

Déployer openGym avec Docker Compose

Le fichier Compose monte ./data et ./media dans des bind mounts relatifs à son propre emplacement. Le répertoire dans lequel vous clonez le dépôt est donc votre base de données. Placez-le à un emplacement persistant.

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 .env

Le README affiche une URL de clonage github.com/DuarteSantos8/openGym. Au 4 novembre 2026, ce dépôt est accessible et se présente comme le dépôt principal du projet. Récupérez le tag avant la première compilation : la branche par défaut a dépassé la version décrite dans ce guide. Dans cette branche, les animations des exercices sont intégrées à l’image et le job de médias décrit plus bas n’existe plus. La section consacrée au verrouillage de version explique pourquoi.

Modifiez .env. Trois lignes sont importantes sur un VPS.

RP_ID=gym.example.com
ORIGIN=https://gym.example.com
WEB_PORT=127.0.0.1:8080

RP_ID est le nom d’hôte seul et ORIGIN est l’URL complète, schéma inclus. Ils doivent correspondre exactement à ce qui apparaît dans la barre d’adresse. Sinon, la connexion échoue avec verification failed. La valeur WEB_PORT est expliquée dans la section consacrée au maintien du port 8080 en privé.

docker compose up -d --build
docker compose ps --all
docker compose logs media

docker compose ps --all doit afficher web et api à l’état running, et media à l’état exited avec le code 0. Conservez l’option --all : sans elle, Compose n’affiche que les conteneurs en cours d’exécution. Le job media terminé n’apparaît donc pas du tout. Cet arrêt est normal : le job de médias a restart: "no", car son travail consiste en un téléchargement exécuté une seule fois. Son journal se termine par une ligne commençant par ✓ Exercise media ready, et ls media/img | wc -l doit afficher 1,324 plutôt que 0. C’est le nombre de miniatures fournies par le jeu de données d’exercices en amont au 9 octobre 2026. Un répertoire vide indique que le téléchargement a échoué. L’application affiche alors des cartes d’exercices avec des images vides.

Conservez l’option --build. Le fichier Compose de ce tag désigne des images précompilées sur ghcr.io avec le tag latest. Ces images sont de nouveau publiées au 18 octobre 2026, mais latest suit la version la plus récente. Ainsi, docker compose pull exécuterait du code plus récent que celui du source que vous venez de récupérer. Les deux services comportent une section build, et --build les compile à partir de votre copie de travail. Si Compose est nouveau pour vous, commencez par Docker Compose sur un VPS, puis revenez ici.

Épinglez la version, car ce projet est encore récent

Le registre contient de nouveau des images versionnées, mais le fichier Compose de v1.2.7 demande toujours latest. Au 4 novembre 2026, latest pointe vers 1.4.4, publiée le 3 novembre 2026. Ce que vous épinglez est le checkout présent sur le disque, car il détermine la version de l’application qui se retrouve dans le conteneur.

cd /opt/opengym
git fetch --tags
git checkout v1.2.7

git status indique maintenant un HEAD détaché sur ce tag, ce qui est le comportement souhaité sur un serveur. Rien ne change tant que vous n’effectuez pas le checkout d’un autre tag.

v1.2.7 est la version sur laquelle ce guide a été écrit, et ce n’est plus la plus récente. Les versions ultérieures modifient le déploiement lui-même (sur la branche par défaut, le job media a disparu). Consultez donc les notes de version et comparez le fichier Compose avant de déplacer le pin. Les notes de version de v1.4.2 et v1.4.3 signalent également des correctifs de sécurité, et le projet demande aux personnes qui auto-hébergent le service de mettre à jour.

Demandez ensuite à Compose de ne plus consulter le registre. Placez ceci dans docker-compose.override.yml, que Compose charge automatiquement et fusionne par-dessus le fichier suivi. Les clés scalaires sont remplacées par celles du fichier d’override. Vous n’avez donc rien à modifier dans git, et git pull reste propre. Consultez la fusion d’un fichier d’override par Compose pour connaître toutes les règles de fusion.

services:
  api:
    pull_policy: build
  web:
    pull_policy: build

Avec cette configuration, un prochain docker compose up -d construira l’application à partir des sources présentes sur votre système au lieu de télécharger ce vers quoi latest pointe ce jour-là. Vérifiez que la fusion a bien été appliquée, puis reconstruisez à partir du tag.

docker compose config | grep pull_policy
docker compose up -d --build

Terminer TLS avec un reverse proxy

Les conteneurs utilisent HTTP en clair. Un composant placé en amont doit gérer le certificat. Caddy est la solution la plus simple, car il demande et renouvelle lui-même le certificat auprès de Let's Encrypt.

gym.example.com {
    reverse_proxy 127.0.0.1:8080
}

nginx, Traefik et Nginx Proxy Manager fonctionnent de la même manière. Un Cloudflare Tunnel convient également. Le projet le documente et il ne nécessite aucun port entrant ouvert.

curl -sI https://gym.example.com | head -1

Cette commande doit retourner HTTP/2 200 sans avertissement de certificat. Ouvrez ensuite le site dans un navigateur et cliquez sur Create profile. Si l’invite de passkey s’affiche, puis que la connexion renvoie verification failed, RP_ID ou ORIGIN ne correspond pas à l’URL affichée dans la barre d’adresse. Corrigez .env et exécutez de nouveau docker compose up -d. Cette commande recrée les conteneurs afin qu’ils lisent les nouvelles valeurs. Un docker compose restart ne recharge pas .env.

Ne laissez pas le port 8080 accessible depuis Internet

Par défaut, le service web publie 8080 sur toutes les interfaces. L’application est donc accessible en HTTP simple via votre IP publique, tandis que le proxy fournit HTTPS sur le même serveur. Une règle de pare-feu ne corrige pas ce problème. Docker publie un port au moyen d’une règle DNAT dans la table nat. Ce trafic est ensuite traité dans la chaîne FORWARD, où les propres règles de Docker l’acceptent, tandis que les règles d’ufw se trouvent sur le chemin INPUT. sudo ufw deny 8080/tcp ne bloque donc rien.

La solution consiste à publier le port uniquement sur l’adresse loopback. Le fichier Compose mappe "${WEB_PORT:-8080}:${NGINX_PORT:-80}". La valeur définie dans WEB_PORT est donc substituée à gauche de ce mapping, et la syntaxe abrégée de Docker accepte une paire ip:port à cet endroit. C’est pourquoi WEB_PORT=127.0.0.1:8080 fonctionne.

docker compose config
sudo ss -ltnp | grep 8080

Dans la configuration fusionnée, sous la section ports du service web, vous devez voir host_ip: 127.0.0.1. ss doit afficher 127.0.0.1:8080, et non 0.0.0.0:8080. Depuis une autre machine, curl http://<your-vps-ip>:8080 doit désormais être refusé ou expirer, tandis que le hostname HTTPS continue de fonctionner.

Fermer les inscriptions une fois votre profil créé

Les inscriptions sont ouvertes par défaut et le mode invité est activé. Sur un hostname public, toute personne qui trouve l’URL peut donc créer un profil sur votre serveur. Créez d’abord votre propre profil, puis trouvez votre ID utilisateur : ls data/ affiche un fichier nommé state-<uid>.json pour chaque utilisateur, et ce <uid> correspond à la valeur dont vous avez besoin.

ADMIN_UIDS=<your-uid>
INVITE_ONLY=1
ALLOW_GUEST=0

Exécutez à nouveau docker compose up -d. Settings affiche maintenant un tableau de bord d’administration qui permet de générer et de révoquer des codes d’invitation. Les personnes avec lesquelles vous vous entraînez peuvent ainsi s’inscrire, et personne d’autre. openGym ne connaît pas les fournisseurs d’identité externes. Ces codes d’invitation contrôlent donc uniquement cette application, et rien d’autre sur le serveur. Si vous préférez attribuer un seul compte par personne pour tous les services que vous exécutez, placez Authentik devant comme proxy forward auth afin de contrôler le hostname avant même que la connexion passkey d’openGym ne se charge.

Où résident les données et quelle sauvegarde les protège

Tout se trouve dans le répertoire ./data, monté dans le conteneur API à l’emplacement /data. Il existe quatre types de fichiers : db.json contient les profils et les identifiants de passkeys publics, state-<uid>.json contient les routines, les entraînements et le poids d’un utilisateur, secret contient la clé du cookie de session, et vapid.json contient les clés de notifications push générées au premier démarrage.

cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api

Arrêtez d’abord l’API afin que les fichiers restent cohérents entre eux pendant que tar les copie. Dans la version v1.2.7, l’API écrit les fichiers JSON de la base de données et de l’état des entraînements dans un fichier temporaire, puis le renomme par-dessus le fichier cible de manière atomique. Elle ne réécrit donc pas directement ces fichiers actifs. Copiez ensuite l’archive hors du serveur, car une archive stockée sur le VPS ne survit pas à la perte du VPS. N’incluez pas media/ dans la sauvegarde : ce répertoire contient 140 MB d’images d’exercices que le job de médias peut télécharger à nouveau gratuitement.

Pour restaurer les données, extrayez l’archive dans le même chemin sur un hôte qui sert le même domaine. Une passkey enregistrée sur votre téléphone est associée au RP ID sur lequel elle a été créée. Une restauration sur un nouveau nom d’hôte vous donne donc une base de données fonctionnelle, mais personne ne peut s’y connecter. Conservez le domaine ou prévoyez de réenregistrer chaque passkey. La même méthode s’applique à tout le reste de votre infrastructure, et sauvegarder et mettre à niveau une stack Docker Compose décrit la procédure générale.

Le serveur MCP épinglé est en lecture seule et s’exécute sur votre machine

MCP (model context protocol) permet à un client tel que Claude Desktop ou Cursor de communiquer avec un serveur d’outils local. openGym en fournit un dans mcp/. Il ne fait pas partie du fichier compose, ce n’est pas un conteneur et il n’écoute sur aucun port. Le client le démarre comme processus enfant et communique avec lui via stdio. Le serveur épinglé lit uniquement les fichiers locaux ; le serveur actuel envoie également les enregistrements d’entraînement à votre API openGym associée.

Installez-le là où le client s’exécute, et non sur le serveur :

cd openGym/mcp
npm install

Ajoutez-le ensuite à 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 est facultatif sur une installation mono-utilisateur, où le serveur détecte le seul profil trouvé. Dans la branche par défaut actuelle, il expose onze outils : list_routines, get_routine, preview_session, get_week_plan, list_workouts, get_workout, get_bodyweight, estimate_1rm, muscle_balance, get_programme et log_workout. preview_session affiche ce que l’application montrera réellement à l’écran lorsque vous démarrez une routine, après que la règle de progression et votre historique ont modifié le plan. Le tag v1.2.7 fournissait huit outils en lecture seule, sans preview_session, get_programme ni log_workout. Un assistant utilisant ce serveur épinglé peut répondre à la question de savoir ce que vous avez fait au développé couché la semaine dernière, mais il ne peut pas enregistrer une série, modifier une routine ni rien supprimer. Dans la branche actuelle, dix outils lisent les données et log_workout enregistre les entraînements via votre serveur après l’association ; cet outil reste désactivé tant que l’association n’a pas été effectuée. Cette liste illustre un principe auquel revient constamment la conception d’agents : les outils que vous exposez définissent tout ce qu’un modèle peut faire, et apprendre le fonctionnement des agents en écrivant vous-même la boucle est le moyen le plus rapide de comprendre pourquoi un ensemble d’outils en lecture seule relève d’un choix de conception, et non d’une limitation.

Voici le problème que doit résoudre un utilisateur de VPS. OPENGYM_DATA est un chemin de système de fichiers, tandis que vos données se trouvent sur le VPS et votre client d’IA sur votre ordinateur portable. Deux options qui tiennent compte de cette réalité :

  1. Copiez les données localement et indiquez au serveur d’utiliser cette copie : rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/, puis définissez OPENGYM_DATA sur ~/opengym-data. Le serveur épinglé lit uniquement les données, donc une copie n’entraîne aucune perte. Relancez rsync lorsque vous voulez actualiser les données.
  2. Exécutez le serveur via ssh, en définissant command sur ssh et args sur ["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Node doit être installé sur le VPS. Le compte de connexion ne doit rien écrire sur stdout, car stdout transporte le protocole.

Les deux options supposent que l’agent lui-même s’exécute sur votre ordinateur portable. Si vous préférez l’exécuter sur la même machine que les données, OneCLI fournit à chaque personne un agent isolé sur le serveur, et le saut stdio vers data/ redevient local.

Si cat data/db.json renvoie Permission denied, le conteneur API a créé ces fichiers avec root et votre compte de connexion ne peut pas les lire. Copiez-les avec sudo ou modifiez leur propriétaire sur l’hôte. Pour les serveurs conçus pour écouter sur le réseau plutôt que via stdio, consultez exécuter des serveurs MCP sur un VPS.

openGym ou wger : lequel déployer ?

wger est l’option établie dans ce domaine et constitue un logiciel beaucoup plus volumineux. Sa stack Compose exécute gunicorn pour servir une application Django, PostgreSQL, Redis et un worker Celery derrière nginx. En contrepartie, vous bénéficiez du suivi de la nutrition et des ingrédients, d’une API REST documentée, d’une vaste base d’exercices et de fonctions destinées aux coachs qui gèrent les programmes d’autres personnes.

openGym se compose de deux conteneurs, d’un dossier de fichiers JSON et d’aucun compte à administrer, à part les passkeys. C’est toute la différence. Si vous avez déjà maintenu une installation de Chatwoot, avec une sauvegarde constituée d’un dump Postgres accompagné du répertoire des fichiers importés, et chaque mise à niveau qui exécute des migrations de base de données, vous savez déjà ce que la maintenance de wger implique.

Déployez wger si vous voulez suivre votre alimentation en parallèle de votre entraînement, ou si vous avez besoin d’une API sur laquelle vous appuyer. Déployez openGym si vous voulez une stack assez petite pour être lue de bout en bout en un après-midi, avec une connexion sans mot de passe à compromettre. Le coût de ce choix est la maturité : au 19 août 2026, la première release d’openGym date d’un mois, tandis que wger bénéficie de plusieurs années de releases. Épinglez votre version, conservez les sauvegardes et lisez les notes de release avant chaque mise à jour.

Si vous cherchez encore ce qui mérite de l’espace sur le serveur, ce qui mérite d’être auto-hébergé en 2026 présente les compromis. Cette application trouve aussi facilement sa place à côté de Mealie pour les recettes ou d’Actual Budget pour gérer votre argent sur le même petit VPS.

Mettre à jour sans rien perdre

cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api
git fetch --tags

Récupérez la release souhaitée avec git checkout v<new>, puis exécutez docker compose up -d --build afin de reconstruire les conteneurs à partir de ce tag. La sauvegarde doit toujours être effectuée en premier, car la restauration des fichiers JSON sur disque se fait avec une seule commande tar et ne prend que quelques secondes.

FAQ

Pourquoi openGym n’affiche-t-il jamais de demande de passkey sur mon téléphone ?

Le navigateur refuse de créer une credential parce que vous utilisez http:// ou une simple adresse IP, comme http://192.168.1.20:8080. Les navigateurs autorisent les passkeys uniquement sur des origines HTTPS, à la seule exception de localhost. Placez openGym derrière un reverse proxy avec un vrai certificat pour un vrai nom d’hôte, définissez RP_ID=gym.example.com et ORIGIN=https://gym.example.com dans .env, puis exécutez docker compose up -d pour que les conteneurs prennent en compte les nouvelles valeurs. Si la demande s’affiche, mais que la connexion indique verification failed, ces deux valeurs ne correspondent pas exactement à l’URL affichée dans la barre d’adresse.

Où openGym stocke-t-il mes données et comment les sauvegarder ?

Dans le répertoire ./data situé à côté du fichier Compose, monté dans le conteneur API sous /data. Il contient db.json pour les profils et les credentials passkeys publiques, un fichier state-<uid>.json par utilisateur pour les entraînements et le poids, secret pour la clé des cookies de session et vapid.json pour les clés de notification push. Sauvegardez-le avec docker compose stop api, puis tar czf ~/opengym-$(date +%F).tar.gz data/, puis docker compose start api, et copiez l’archive hors du serveur. Ignorez media/, qui contient 140 MB d’images d’exercices que le job media télécharge de nouveau automatiquement.

Claude peut-il lire mon historique d’entraînement openGym ?

Oui, via le serveur MCP facultatif du répertoire mcp/. Le serveur v1.2.7 épinglé fournit huit outils en lecture seule. La branche par défaut actuelle fournit onze outils : dix routines de lecture pour les sessions, les aperçus, les plans de la semaine, les entraînements, le poids, le 1RM estimé, l’équilibre musculaire et les programmes ; log_workout écrit les entraînements via votre serveur après l’appairage. Il ne s’agit pas d’un conteneur et il n’ouvre aucun port : votre client le démarre via stdio et ses outils de lecture accèdent directement aux fichiers JSON dans OPENGYM_DATA. Comme il s’agit d’un chemin de système de fichiers, exécuter openGym sur un VPS signifie soit synchroniser une copie de data/ vers la machine qui exécute le client, soit invoquer le serveur via ssh dans la configuration du client.

Dois-je auto-héberger openGym ou wger ?

Choisissez wger si vous voulez suivre l’alimentation et la nutrition en plus de vos entraînements, ou disposer d’une API REST documentée sur laquelle vous appuyer. Il exécute une stack plus importante : Django sous gunicorn, PostgreSQL, Redis et un worker Celery derrière nginx. Choisissez openGym si vous voulez deux conteneurs, des fichiers JSON lisibles avec cat et une connexion par passkey sans mot de passe à gérer. Au 19 août 2026, la première release taguée d’openGym date d’un mois seulement. Vérifiez donc un tag git et sauvegardez data/ avant chaque mise à jour.

Cet article vous a-t-il été utile ?