Cómo alojar openGym con Docker Compose y TLS
Despliega openGym en un VPS con Docker Compose: fija una etiqueta de Git, configura TLS antes de la primera Passkey, localiza los datos y activa el MCP opcional.
Qué se obtiene al alojar openGym por cuenta propia
Para alojar openGym por cuenta propia, clone el repositorio, edite dos líneas en .env y ejecute docker compose up -d --build detrás de un proxy inverso que termine TLS (seguridad de la capa de transporte). openGym es un rastreador de gimnasio y peso corporal: planes semanales, entrenamientos guiados, registro de cada serie y evolución del peso. Se distribuye con licencia AGPL-3.0 y almacena todo en archivos JSON sin formato en el disco, por lo que no es necesario ejecutar un servidor de base de datos.
La pila consta de dos contenedores de ejecución prolongada: un contenedor nginx que sirve la compilación de React y un contenedor Node que aloja la API. También incluye un trabajo de una sola ejecución que descarga unos 140 MB de imágenes y GIF de ejercicios la primera vez que se inicia.
El README del proyecto da a entender dos aspectos, pero no los explica para quien despliega el servicio en un servidor público. El inicio de sesión con Passkey está vinculado a un nombre de host, por lo que el dominio y su certificado deben existir antes del primer inicio de sesión, no después. Además, el servidor MCP opcional es de solo lectura en la etiqueta fijada v1.2.7 y se ejecuta en el equipo donde se ejecuta el cliente de IA, no dentro de la pila. Esto cambia las tareas necesarias cuando los datos se encuentran en un VPS. El servidor MCP actual también permite registrar entrenamientos después de emparejarlo con el servidor.
openGym es reciente. La primera versión etiquetada, v1.0.0, está fechada el 20 de julio de 2026, y v1.2.7 se publicó el 18 de agosto de 2026. Trece etiquetas durante su primer mes y 34 hasta el 9 de octubre de 2026, cuando se etiquetó v1.4.0, indican que la aplicación sigue cambiando. Por eso, consulte una etiqueta de versión en lugar de compilar lo que haya en la rama predeterminada.
Planifique el dominio antes del primer inicio de sesión
Las passkeys son el método de inicio de sesión en openGym. Una passkey está vinculada a un relying party ID (RP ID), que es el dominio en el que se creó la credencial, y los navegadores sólo crean passkeys mediante HTTPS. La única excepción es localhost.
Esto tiene una consecuencia que los usuarios encuentran en el teléfono. Abra http://203.0.113.10:8080 desde otro dispositivo y no aparecerá ninguna solicitud para crear una passkey, porque el navegador se niega a crear una credencial en un origen HTTP sin cifrar o en una dirección IP independiente. Las propias notas de solución de problemas del proyecto indican lo mismo: si no aparece ninguna solicitud, está usando http:// o una dirección IP.
Lo más importante es que el RP ID queda incorporado en todas las credenciales que los usuarios ya han registrado. Si cambia RP_ID más adelante, las passkeys almacenadas en sus dispositivos dejarán de coincidir y nadie podrá iniciar sesión. Decida primero el nombre de host, apunte el DNS al VPS y haga funcionar el certificado antes de que alguien pulse Create profile.
Implementar openGym con Docker Compose
El archivo de Compose monta ./data y ./media mediante bind mounts relativos a sí mismo, por lo que el directorio donde lo clone es la base de datos. Colóquelo en una ubicación persistente.
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 .envEl README muestra una URL de clonación github.com/DuarteSantos8/openGym. A fecha de 4 de noviembre de 2026, ese repositorio responde y se describe como la sede del proyecto. Cambie a la etiqueta antes de la primera compilación: la rama predeterminada ha avanzado más allá de la versión que describe esta guía, y en ella las animaciones de los ejercicios se incluyen dentro de la imagen y el trabajo de medios ya no existe. La sección sobre fijación de versiones explica el motivo.
Edite .env. En un VPS, importan tres líneas.
RP_ID=gym.example.com
ORIGIN=https://gym.example.com
WEB_PORT=127.0.0.1:8080RP_ID es el nombre de host sin más, y ORIGIN es la URL completa, incluido el esquema. Deben coincidir exactamente con lo que aparece en la barra de direcciones; de lo contrario, el inicio de sesión falla con verification failed. El valor WEB_PORT se explica en la sección sobre cómo mantener privado el puerto 8080.
docker compose up -d --build
docker compose ps --all
docker compose logs mediadocker compose ps --all debe mostrar web y api en ejecución, y media como terminado con el código 0. Mantenga la opción --all: sin ella, Compose sólo muestra los contenedores en ejecución, por lo que el trabajo media terminado no aparece. Esta terminación es correcta: el trabajo de medios tiene restart: "no" porque su tarea es una descarga única. Su registro termina con una línea que comienza por ✓ Exercise media ready, y ls media/img | wc -l debe mostrar 1,324 en lugar de 0. Ese es el número de miniaturas que el conjunto de datos de ejercicios original incluye a fecha de 9 de octubre de 2026. Un directorio vacío indica que la descarga falló; en ese caso, la aplicación muestra las tarjetas de ejercicios sin imágenes.
Mantenga la opción --build. El archivo de Compose de esta etiqueta nombra imágenes prediseñadas en ghcr.io con la etiqueta latest. Esas imágenes se volvieron a publicar a fecha de 18 de octubre de 2026, pero latest sigue la versión más reciente, por lo que docker compose pull ejecutaría código más nuevo que el código fuente que acaba de comprobar. Ambos servicios incluyen una sección build, y --build los compila a partir de su copia de trabajo. Si Compose es nuevo para usted, empiece por Docker Compose en un VPS y vuelva después.
Fije la versión, porque este proyecto es reciente
El registro vuelve a ofrecer imágenes versionadas, pero el archivo compose de v1.2.7 sigue solicitando latest. A fecha de 4 November 2026, latest apunta a 1.4.4, publicada el 3 November 2026. Lo que debe fijar es el checkout del disco, porque determina qué versión de la aplicación termina en el contenedor.
cd /opt/opengym
git fetch --tags
git checkout v1.2.7git status ahora muestra un HEAD separado en esa etiqueta, que es lo que se necesita en un servidor. No cambiará nada hasta que haga checkout de otra etiqueta.
v1.2.7 es la versión en la que se basa esta guía y ya no es la más reciente. Las versiones posteriores cambian el propio despliegue: en la rama predeterminada, el trabajo de medios ya no existe. Lea las notas de la versión y compare el archivo compose antes de cambiar la versión fijada. Las notas de versión de v1.4.2 y v1.4.3 también informan de correcciones de seguridad, y el proyecto pide a quienes alojan el servicio por su cuenta que actualicen.
A continuación, indique a Compose que deje de acceder al registro. Coloque esto en docker-compose.override.yml, que Compose carga automáticamente y combina sobre el archivo seguido por el control de versiones. Las claves escalares se sustituyen por las del archivo de reemplazo, por lo que no es necesario editar nada en git y git pull permanece limpio. Consulte cómo combina Compose un archivo de reemplazo para conocer todas las reglas de combinación.
services:
api:
pull_policy: build
web:
pull_policy: buildCon esto configurado, un docker compose up -d posterior compila a partir del código fuente disponible en lugar de extraer lo que latest indique ese día. Compruebe que la combinación se haya aplicado y vuelva a compilar en la etiqueta.
docker compose config | grep pull_policy
docker compose up -d --buildFinalice TLS con un proxy inverso
Los contenedores usan HTTP sin cifrar. Un componente situado delante debe gestionar el certificado. Caddy es la opción más sencilla, porque solicita y renueva el certificado de Let's Encrypt automáticamente.
gym.example.com {
reverse_proxy 127.0.0.1:8080
}nginx, Traefik y Nginx Proxy Manager funcionan de la misma forma. Cloudflare Tunnel también, y el proyecto lo documenta. Además, no necesita abrir ningún puerto entrante.
curl -sI https://gym.example.com | head -1El comando debe devolver HTTP/2 200 sin mostrar una advertencia sobre el certificado. Ahora abra el sitio en un navegador y pulse Create profile. Si aparece el aviso para crear una passkey y después el inicio de sesión muestra un error, verification failed, RP_ID o ORIGIN no coincide con la URL de la barra de direcciones. Corrija .env y vuelva a ejecutar docker compose up -d. Esto recrea los contenedores para que lean los valores nuevos. Un docker compose restart no vuelve a cargar .env.
Mantener el puerto 8080 fuera de Internet pública
De forma predeterminada, el servicio web publica 8080 en todas las interfaces. Por tanto, la aplicación es accesible mediante HTTP sin cifrar en la IP pública, mientras el proxy sirve HTTPS en el mismo equipo. Una regla del firewall no corrige este problema. Docker publica un puerto mediante una regla DNAT en la tabla nat. Después, ese tráfico se procesa en la cadena FORWARD, donde las reglas propias de Docker lo aceptan, mientras las reglas de ufw se encuentran en la ruta INPUT. Por eso, sudo ufw deny 8080/tcp no bloquea nada.
La solución es publicar el puerto sólo en la dirección de loopback. El archivo compose asigna "${WEB_PORT:-8080}:${NGINX_PORT:-80}". Por tanto, el valor que establezca en WEB_PORT se sustituye a la izquierda de esa asignación, y la sintaxis abreviada de Docker acepta allí un par ip:port. Por eso funciona WEB_PORT=127.0.0.1:8080.
docker compose config
sudo ss -ltnp | grep 8080En la configuración combinada, dentro de ports del servicio web, debe aparecer host_ip: 127.0.0.1. ss debe mostrar 127.0.0.1:8080 y no 0.0.0.0:8080. Desde otra máquina, curl http://<your-vps-ip>:8080 debería rechazarse o agotar el tiempo de espera, mientras el nombre de host HTTPS sigue funcionando.
Cierre el registro cuando su perfil exista
El registro está abierto de forma predeterminada y el modo invitado está activado. En un nombre de host público, cualquiera que encuentre la URL puede crear un perfil en su servidor. Registre primero su propio perfil y, después, busque su ID de usuario: ls data/ muestra un archivo llamado state-<uid>.json para cada usuario, y ese <uid> es el valor que necesita.
ADMIN_UIDS=<your-uid>
INVITE_ONLY=1
ALLOW_GUEST=0Vuelva a ejecutar docker compose up -d. Ahora Settings muestra un panel de administración donde puede generar y revocar códigos de invitación. Así, las personas con las que entrena pueden registrarse y nadie más. openGym no conoce los proveedores de identidad externos. Por tanto, esos códigos de invitación controlan sólo esta aplicación y ninguna otra del servidor. Si prefiere asignar una sola cuenta a cada persona para todos los servicios que ejecuta, coloque Authentik delante como proxy de autenticación delegada. De este modo, el proxy controla el nombre de host antes de que se cargue el inicio de sesión propio de openGym mediante passkey.
Dónde se almacenan los datos y qué copia de seguridad los protege
Todo está en el directorio ./data, montado en el contenedor de la API en /data. Hay cuatro tipos de archivo: db.json contiene los perfiles y las credenciales públicas de passkey, state-<uid>.json contiene las rutinas, los entrenamientos y el peso corporal de un usuario, secret es la clave de la cookie de sesión y vapid.json contiene las claves de notificaciones push generadas durante la primera ejecución.
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start apiDetenga primero la API para que los archivos mantengan la coherencia entre sí mientras tar los copia. En v1.2.7, la API escribe el JSON de la base de datos y del estado del entrenamiento en un archivo temporal y cambia su nombre sobre el destino de forma atómica. Por tanto, no reescribe esos archivos activos directamente. Después, copie el archivo comprimido fuera del servidor, porque un archivo almacenado en el VPS no sobrevive a la pérdida del VPS. Excluya media/ de la copia de seguridad: contiene 140 MB de imágenes de ejercicios que el trabajo multimedia vuelve a descargar sin coste.
Para restaurar los datos, extraiga el archivo en la misma ruta de un host que sirva el mismo dominio. Una passkey almacenada en el teléfono está vinculada al RP ID con el que se creó. Por tanto, restaurarla en un nombre de host nuevo le proporcionará una base de datos funcional, pero nadie podrá iniciar sesión. Mantenga el dominio o planifique volver a registrar todas las passkeys. La misma disciplina se aplica al resto de servicios que ejecute; la copia de seguridad y la actualización de una pila de Docker Compose cubre el procedimiento general.
El servidor MCP fijado es de solo lectura y se ejecuta en su máquina
MCP (model context protocol) es el mecanismo que usa un cliente como Claude Desktop o Cursor para comunicarse con un servidor de herramientas local. openGym incluye uno en mcp/. No forma parte del archivo compose, no es un contenedor y no escucha en ningún puerto. El cliente lo inicia como proceso hijo y se comunica con él mediante stdio. El servidor fijado sólo lee archivos locales; el servidor actual también envía las escrituras de entrenamientos a su API de openGym emparejada.
Instálelo donde se ejecuta el cliente, no en el servidor:
cd openGym/mcp
npm installDespués, añádalo a 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 es opcional en una instalación para un solo usuario, porque el servidor detecta el único perfil que encuentra. En la rama predeterminada actual expone once herramientas: list_routines, get_routine, preview_session, get_week_plan, list_workouts, get_workout, get_bodyweight, estimate_1rm, muscle_balance, get_programme y log_workout. preview_session muestra lo que la aplicación realmente pondrá en pantalla al iniciar una rutina, después de que la política de progresión y su historial hayan modificado el plan. La etiqueta v1.2.7 incluía ocho herramientas de solo lectura, sin preview_session, get_programme ni log_workout. Un asistente que usa ese servidor fijado puede responder qué ejercicio de press de banca hizo la semana pasada, pero no puede registrar una serie, editar una rutina ni eliminar nada. En la rama actual, diez herramientas leen datos y log_workout guarda entrenamientos mediante su servidor después del emparejamiento; permanece desactivada hasta que se empareja. Esta lista es un ejemplo conciso de una decisión a la que el diseño de agentes vuelve continuamente: las herramientas que expone determinan todo lo que puede hacer un modelo, y aprender cómo funcionan los agentes escribiendo usted mismo el bucle es la forma más rápida de entender por qué un conjunto de herramientas de solo lectura es una decisión de diseño y no una limitación.
Esta es la parte que debe resolver quien usa un VPS. OPENGYM_DATA es una ruta del sistema de archivos, pero sus datos están en el VPS y el cliente de IA está en su portátil. Hay dos opciones que reflejan esta situación sin ocultarla.
- Copie los datos y configure el servidor para que use la copia:
rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/; después, establezcaOPENGYM_DATAen~/opengym-data. El servidor fijado sólo lee, por lo que una copia no pierde nada. Vuelva a ejecutar rsync cuando necesite datos actualizados. - Ejecute el servidor mediante ssh, con
commandestablecido ensshyargsestablecido en["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Node debe estar instalado en el VPS y la sesión de inicio de sesión no debe imprimir nada en stdout, porque stdout es el canal del protocolo.
Ambas opciones suponen que el propio agente se ejecuta en su portátil. Si prefiere ejecutarlo en el mismo equipo que contiene los datos, OneCLI proporciona a cada persona un agente aislado en el servidor, de modo que el salto de stdio hasta data/ vuelve a ser local.
Si cat data/db.json devuelve Permission denied, el contenedor de la API escribió esos archivos como root y su cuenta no puede leerlos. Cópielos con sudo o cambie el propietario en el host. Para servidores que deben escuchar en la red en lugar de hacerlo mediante stdio, consulte ejecutar servidores MCP en un VPS.
openGym o wger: ¿cuál debería ejecutar?
wger es la opción consolidada en este ámbito y es un software mucho más grande. Su stack de Compose ejecuta gunicorn para servir una aplicación Django, PostgreSQL, Redis y un worker de Celery detrás de nginx. A cambio, ofrece seguimiento de la nutrición y los ingredientes, una API REST documentada, una base de datos grande de ejercicios y funciones para entrenadores que gestionan los planes de otras personas.
openGym consta de dos contenedores, una carpeta de archivos JSON y ninguna cuenta que administrar aparte de las passkeys. Esa es toda la diferencia. Si alguna vez mantuvo una instalación de Chatwoot, donde una copia de seguridad consiste en un volcado de Postgres junto al directorio de cargas y cada actualización de versión ejecuta migraciones de base de datos, ya conoce el tipo de mantenimiento que exige wger.
Ejecute wger si quiere registrar la alimentación junto con el entrenamiento o si necesita una API sobre la que desarrollar. Ejecute openGym si quiere un stack lo bastante pequeño para leerlo de principio a fin en una tarde y un inicio de sesión sin contraseña que pueda filtrarse. El coste de esa elección es la madurez: a 19 August 2026, la primera versión de openGym tiene un mes, mientras que wger acumula años de versiones. Fije la versión, conserve las copias de seguridad y lea las notas de la versión antes de cada actualización.
Si todavía está decidiendo qué merece espacio en el servidor, qué merece la pena alojar por cuenta propia en 2026 explica las ventajas y desventajas, y esta aplicación encaja bien junto a Mealie para recetas o Actual Budget para las finanzas en el mismo VPS pequeño.
Actualizar sin perder datos
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api
git fetch --tagsCambie a la versión que necesita con git checkout v<new> y, después, ejecute docker compose up -d --build para reconstruir los contenedores a partir de esa etiqueta. La copia de seguridad se hace siempre primero, porque restaurar los archivos JSON del disco requiere un único comando tar y tarda unos segundos.
FAQ
¿Por qué openGym nunca muestra una solicitud de passkey en mi teléfono?
El navegador se niega a crear una credencial porque está en http:// o en una dirección IP sin nombre de host, como http://192.168.1.20:8080. Los navegadores sólo permiten passkeys en orígenes HTTPS, con localhost como única excepción. Coloque openGym detrás de un proxy inverso que use un certificado válido para un nombre de host real, establezca RP_ID=gym.example.com y ORIGIN=https://gym.example.com en .env y ejecute docker compose up -d para que los contenedores recojan los nuevos valores. Si aparece la solicitud, pero el inicio de sesión muestra verification failed, esos dos valores no coinciden exactamente con la URL de la barra de direcciones.
¿Dónde almacena openGym mis datos y cómo puedo hacer una copia de seguridad?
En el directorio ./data situado junto al archivo compose, montado en el contenedor de la API como /data. Contiene db.json para los perfiles y las credenciales públicas de passkey, un archivo state-<uid>.json por usuario para los entrenamientos y el peso corporal, secret para la clave de las cookies de sesión y vapid.json para las claves de notificaciones push. Haga una copia de seguridad con docker compose stop api, después con tar czf ~/opengym-$(date +%F).tar.gz data/ y luego con docker compose start api, y copie el archivo comprimido fuera del servidor. Omita media/, que ocupa 140 MB de imágenes de ejercicios que el trabajo de medios vuelve a descargar por su cuenta.
¿Puede Claude leer mi historial de entrenamientos de openGym?
Sí, mediante el servidor MCP opcional del directorio mcp/. El servidor fijado en v1.2.7 tiene ocho herramientas de sólo lectura. La rama predeterminada actual tiene once herramientas: diez rutinas de lectura para sesiones, vistas previas, planes semanales, entrenamientos, peso corporal, una repetición máxima estimada, equilibrio muscular y programas; log_workout escribe entrenamientos en el servidor después de emparejarse. No es un contenedor y no abre ningún puerto: el cliente lo inicia mediante stdio y sus herramientas de lectura acceden directamente a los archivos JSON en OPENGYM_DATA. Como se trata de una ruta del sistema de archivos, ejecutar openGym en un VPS requiere sincronizar una copia de data/ con el equipo donde se ejecuta el cliente o invocar el servidor mediante ssh desde la configuración del cliente.
¿Debería alojar openGym o wger en mi propio servidor?
Elija wger si quiere gestionar alimentos y nutrición junto al registro de entrenamiento, o si necesita una API REST documentada sobre la que desarrollar. Ejecuta una pila más grande: Django con gunicorn, PostgreSQL, Redis y un worker de Celery detrás de nginx. Elija openGym si quiere dos contenedores, archivos JSON que pueda leer con cat y autenticación mediante passkey sin tener que gestionar contraseñas. Al 19 de agosto de 2026, la primera versión etiquetada de openGym tiene un mes, así que cambie a un tag de git y haga una copia de seguridad de data/ antes de cada actualización.