SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-11-06

Como hospedar o openGym com Docker Compose

Veja como implantar o openGym em um VPS com Docker Compose, fixar uma tag Git, configurar TLS antes da primeira passkey, localizar os dados e ativar o MCP.

O que você obtém ao hospedar o openGym por conta própria

Você hospeda o openGym por conta própria clonando o repositório, editando duas linhas em .env e executando docker compose up -d --build atrás de um reverse proxy que termina o TLS (segurança da camada de transporte). O openGym é um rastreador de treinos e peso corporal: planos semanais, treinos guiados, registo de cada série e evolução do peso ao longo do tempo. O software é licenciado sob a AGPL-3.0 e armazena tudo em ficheiros JSON simples no disco, por isso não é necessário executar um servidor de base de dados.

A stack é composta por dois contentores de longa duração: um contentor nginx, que serve a build React, e um contentor Node, que aloja a API. Existe também um job executado uma única vez, que descarrega cerca de 140 MB de imagens e GIFs de exercícios na primeira inicialização.

O README do projeto indica duas coisas, mas não as explica claramente para quem implementa o serviço num servidor público. O início de sessão com passkey está associado a um hostname, por isso o domínio e o respetivo certificado têm de existir antes do primeiro início de sessão, e não depois. Além disso, o servidor MCP opcional é apenas de leitura na tag v1.2.7 fixada e é executado na máquina onde o cliente de IA está em execução, não dentro da stack. Isto altera os passos necessários quando os dados estão num VPS. O servidor MCP atual também permite registar treinos depois de emparelhar com o seu servidor.

O openGym ainda é recente. A primeira release marcada, v1.0.0, está datada de 20 July 2026, e a v1.2.7 foi publicada em 18 August 2026. Foram criadas 13 tags no primeiro mês e 34 até 9 October 2026, quando a v1.4.0 foi marcada. Isto significa que a aplicação ainda está a evoluir. Por isso, faça checkout de uma tag de release em vez de compilar o que estiver na branch predefinida.

Planeje o domínio antes do primeiro login

As passkeys são usadas para iniciar sessão no openGym. Uma passkey está vinculada a um relying party ID (RP ID), que é o domínio no qual a credencial foi criada, e os navegadores só criam passkeys por HTTPS. A única exceção é localhost.

Isso tem uma consequência que os utilizadores encontram no telemóvel. Abra http://203.0.113.10:8080 noutro dispositivo e não aparecerá qualquer pedido para criar uma passkey, porque o navegador recusa criar uma credencial numa origem HTTP simples ou num endereço IP sem nome de domínio. As próprias notas de resolução de problemas do projeto dizem o mesmo: a ausência do pedido significa que está em http:// ou num IP.

O problema é ainda maior porque o RP ID fica gravado em todas as credenciais que os utilizadores já registaram. Se alterar RP_ID mais tarde, as passkeys guardadas nos dispositivos deixam de corresponder e ninguém conseguirá iniciar sessão. Decida primeiro o hostname, aponte o DNS para o VPS e faça o certificado funcionar antes de alguém tocar em Create profile.

Implemente o openGym com Docker Compose

O ficheiro Compose monta ./data e ./media relativos à sua própria localização. Por isso, o diretório onde faz o clone é a sua base de dados. Coloque-o num local 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 .env

O README apresenta um URL de clone github.com/DuarteSantos8/openGym. Em 4 de novembro de 2026, esse repositório está acessível e identifica-se como a página principal do projeto. Faça checkout da tag antes da primeira compilação: o branch predefinido avançou para além da versão descrita neste guia. Nesse branch, as animações dos exercícios já são incluídas na imagem e o job de media abaixo já não existe. A secção sobre fixação de versões explica o motivo.

Edite .env. Num VPS, três linhas são importantes.

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

RP_ID é o hostname simples e ORIGIN é o URL completo, incluindo o esquema. Devem corresponder exatamente ao endereço apresentado na barra do navegador. Caso contrário, o login falha com verification failed. O valor WEB_PORT é explicado na secção sobre como manter a porta 8080 privada.

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

docker compose ps --all deve mostrar web e api como em execução, e media como terminado com o código 0. Mantenha a flag --all: sem ela, o Compose lista apenas os contentores em execução. Por isso, o job media concluído não aparece. Esse estado terminado está correto: o job de media tem restart: "no" porque o seu trabalho é uma transferência única. O respetivo log termina com uma linha que começa por ✓ Exercise media ready, e ls media/img | wc -l deve apresentar 1,324 em vez de 0. Esse é o número de miniaturas incluídas no dataset de exercícios upstream em 9 de outubro de 2026. Um diretório vazio significa que a transferência falhou. Nesse caso, a aplicação apresenta cartões de exercícios com imagens vazias.

Mantenha a flag --build. O ficheiro Compose desta tag identifica imagens pré-compiladas em ghcr.io com a tag latest. Essas imagens foram publicadas novamente em 18 de outubro de 2026, mas latest segue a versão mais recente. Por isso, docker compose pull executaria código mais recente do que o código-fonte que acabou de obter. Ambos os serviços incluem uma secção build, e --build compila-os a partir do seu checkout. Se ainda não conhece o Compose, comece por Docker Compose num VPS e depois volte aqui.

Fixe a versão, porque este projeto ainda é recente

O registry voltou a disponibilizar imagens versionadas, mas o ficheiro compose em v1.2.7 ainda pede latest. Em 4 de novembro de 2026, latest aponta para 1.4.4, lançada em 3 de novembro de 2026. O que deve fixar é o checkout no disco, porque ele determina qual versão da aplicação fica no contentor.

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

git status agora indica um HEAD desanexado nessa tag, que é o comportamento pretendido num servidor. Nada muda até fazer checkout de outra versão.

v1.2.7 é a versão usada como referência neste guia e já não é a mais recente. As versões posteriores alteram o próprio processo de implementação (no branch predefinido, o trabalho de media foi removido), por isso leia as notas de versão e compare o ficheiro compose antes de alterar a versão fixada. As notas de versão de v1.4.2 e v1.4.3 também indicam correções de segurança, e o projeto pede aos operadores que atualizem as instalações.

Depois, configure o Compose para deixar de consultar o registry. Coloque isto em docker-compose.override.yml, que o Compose carrega automaticamente e combina com o ficheiro controlado pelo sistema de versões. As chaves escalares são substituídas pelo override, por isso não é necessário editar nada no git e git pull permanece limpo. Consulte como o Compose combina um ficheiro de override para conhecer todas as regras de combinação.

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

Com essa configuração, um docker compose up -d posterior compila a partir do código-fonte que tem, em vez de obter o que quer que latest indique nesse dia. Confirme se a combinação foi aplicada e depois faça novamente a compilação na tag.

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

Termine o TLS com um reverse proxy

Os contentores comunicam por HTTP simples. Um componente à frente deles tem de gerir o certificado. O Caddy é o caminho mais curto, porque solicita e renova o certificado da Let's Encrypt automaticamente.

gym.example.com {
    reverse_proxy 127.0.0.1:8080
}

nginx, Traefik e Nginx Proxy Manager funcionam da mesma forma. O mesmo acontece com um Cloudflare Tunnel, que está documentado pelo projeto e não exige nenhuma porta de entrada aberta.

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

Isto deve devolver HTTP/2 200 sem aviso de certificado. Agora abra o site num navegador e selecione Create profile. Se o pedido de passkey aparecer e o início de sessão devolver verification failed, RP_ID ou ORIGIN não corresponde ao URL na barra de endereço. Corrija .env e execute docker compose up -d novamente. Isto recria os contentores para que leiam os novos valores. Um docker compose restart não recarrega .env.

Mantenha a porta 8080 fora da Internet pública

Por predefinição, o serviço web publica 8080 em todas as interfaces. Assim, a aplicação fica acessível por HTTP simples no seu IP público, enquanto o proxy fornece HTTPS no mesmo servidor. Uma regra de firewall não corrige este problema. O Docker publica uma porta com uma regra DNAT na tabela nat, e esse tráfego é depois processado na cadeia FORWARD, onde as próprias regras do Docker o aceitam, enquanto as regras do ufw ficam no caminho INPUT. Por isso, sudo ufw deny 8080/tcp não bloqueia nada.

A solução é publicar apenas no endereço de loopback. O ficheiro compose mapeia "${WEB_PORT:-8080}:${NGINX_PORT:-80}". Assim, o valor definido em WEB_PORT é substituído no lado esquerdo desse mapeamento, e a sintaxe curta do Docker aceita aí um par ip:port. É por isso que WEB_PORT=127.0.0.1:8080 funciona.

docker compose config
sudo ss -ltnp | grep 8080

Na configuração consolidada, em ports do serviço web, deve ver host_ip: 127.0.0.1. ss deve mostrar 127.0.0.1:8080, e não 0.0.0.0:8080. A partir de outra máquina, curl http://<your-vps-ip>:8080 deve ser recusado ou exceder o tempo limite. O hostname HTTPS deve continuar a funcionar.

Feche o registo depois de criar o seu perfil

O registo está aberto por predefinição e o modo convidado está ativo. Num hostname público, isso significa que qualquer pessoa que encontre o URL pode criar um perfil no seu servidor. Crie primeiro o seu próprio perfil e, em seguida, encontre o seu ID de utilizador: ls data/ apresenta um ficheiro chamado state-<uid>.json para cada utilizador, e esse <uid> é o valor de que precisa.

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

Execute docker compose up -d novamente. Em Settings, aparece agora um painel de administração onde pode gerar e revogar códigos de convite. Assim, as pessoas com quem treina podem registar-se, mas mais ninguém. O openGym não conhece fornecedores de identidade externos. Por isso, estes códigos de convite controlam apenas esta aplicação e nada mais no servidor. Se preferir atribuir uma única conta a cada pessoa em todos os serviços que executa, coloque o Authentik à frente como um proxy de forward auth. Assim, o hostname é protegido antes de o login por passkey do openGym ser carregado.

Onde os dados ficam e o backup que os protege

Tudo está no diretório ./data, montado no contentor da API em /data. Existem quatro tipos de ficheiro: db.json contém os perfis e as credenciais públicas de passkeys, state-<uid>.json contém as rotinas, os treinos e o peso corporal de um utilizador, secret é a chave dos cookies de sessão e vapid.json contém as chaves de notificações push geradas na primeira execução.

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

Pare primeiro a API para manter os ficheiros consistentes entre si enquanto tar os copia. Na v1.2.7, a API escreve o JSON da base de dados e do estado dos treinos num ficheiro temporário e muda-lhe o nome para o substituir atomicamente no destino. Assim, não reescreve esses ficheiros ativos diretamente. Depois, copie o arquivo para fora do servidor, porque um arquivo armazenado na VPS não sobrevive à perda da VPS. Exclua media/ do backup: são 140 MB de imagens de exercícios que o trabalho de media volta a descarregar gratuitamente.

Restaurar significa extrair o arquivo para o mesmo caminho num host que serve o mesmo domínio. Uma passkey armazenada no telefone está associada ao RP ID em que foi criada, por isso restaurar os dados num hostname novo fornece uma base de dados funcional, mas ninguém consegue iniciar sessão. Mantenha o domínio ou planeie voltar a registar todas as passkeys. A mesma disciplina aplica-se a tudo o que executar, e fazer backup e atualizar uma stack Docker Compose cobre a rotina geral.

O servidor MCP fixado é somente de leitura e é executado na sua máquina

MCP (model context protocol) é a forma como um cliente, como Claude Desktop ou Cursor, comunica com um servidor de ferramentas local. O openGym fornece um em mcp/. Ele não faz parte do ficheiro compose, não é um contentor e não escuta em nenhuma porta. O cliente inicia-o como um processo filho e comunica com ele através de stdio. O servidor fixado apenas lê ficheiros locais; o servidor atual também envia gravações de treinos para a sua API openGym associada.

Instale-o onde o cliente é executado, não no servidor:

cd openGym/mcp
npm install

Depois, adicione-o 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 é opcional numa instalação de utilizador único, na qual o servidor deteta o único perfil encontrado. Na branch predefinida atual, expõe onze ferramentas: list_routines, get_routine, preview_session, get_week_plan, list_workouts, get_workout, get_bodyweight, estimate_1rm, muscle_balance, get_programme e log_workout. preview_session mostra o que a aplicação vai efetivamente apresentar no ecrã quando inicia uma rotina, depois de a política de progressão e o seu histórico substituírem o plano. A tag v1.2.7 fornecia oito ferramentas somente de leitura, sem preview_session, get_programme ou log_workout. Um assistente que use esse servidor fixado pode responder ao que levantou no banco na semana passada, mas não pode registar uma série, editar uma rotina nem apagar nada. Na branch atual, dez ferramentas leem e log_workout guarda treinos através do seu servidor depois da associação; fica desativado até ser associado. Essa lista é um exemplo compacto da decisão à qual o design de agentes regressa repetidamente: as ferramentas que expõe definem tudo o que um modelo pode fazer, e aprender como os agentes funcionam escrevendo o ciclo por si próprio é a forma mais rápida de perceber por que motivo um conjunto de ferramentas somente de leitura é uma escolha de design, e não uma limitação.

Esta é a parte que um utilizador de VPS tem de resolver. OPENGYM_DATA é um caminho do sistema de ficheiros, e os seus dados estão na VPS enquanto o cliente de IA está no seu portátil. Há duas opções que representam essa situação corretamente.

  1. Copie os dados para o portátil e aponte o servidor para a cópia: rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/, e depois defina OPENGYM_DATA como ~/opengym-data. O servidor fixado apenas lê, por isso uma cópia não perde dados. Execute novamente o rsync quando quiser obter números atualizados.
  2. Execute o servidor através de ssh, com command definido como ssh e args definido como ["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Isto requer que Node esteja instalado na VPS e que o login não escreva nada em stdout, porque stdout é o canal do protocolo.

Ambas as opções pressupõem que o próprio agente está no seu portátil. Se preferir executá-lo na mesma máquina onde estão os dados, OneCLI fornece a cada pessoa um agente isolado numa sandbox no servidor, para que o salto de stdio de volta para data/ seja novamente local.

Se cat data/db.json devolver Permission denied, o contentor da API escreveu esses ficheiros como root e a sua conta não consegue lê-los. Copie-os com sudo ou altere o proprietário no host. Para servidores que devem escutar na rede em vez de através de stdio, consulte executar servidores MCP numa VPS.

openGym ou wger: qual deve executar?

O wger é a opção estabelecida neste nicho e é um software muito maior. A stack do Compose executa o gunicorn para servir uma aplicação Django, o PostgreSQL, o Redis e um worker do Celery atrás do nginx. Em troca, oferece acompanhamento de nutrição e ingredientes, uma API REST documentada, uma base de dados extensa de exercícios e funcionalidades para treinadores gerirem os planos de outras pessoas.

O openGym é composto por dois contentores, uma pasta de ficheiros JSON e nenhuma conta para administrar além de passkeys. Essa é toda a diferença. Se já manteve uma instalação do Chatwoot em funcionamento, sabendo que um backup significa um dump do Postgres juntamente com o diretório de uploads e que cada atualização de versão executa migrações da base de dados, já sabe o que a estrutura do wger exige em termos de manutenção.

Execute o wger se quiser acompanhar a alimentação juntamente com o treino ou se precisar de uma API para desenvolver sobre ela. Execute o openGym se quiser uma stack suficientemente pequena para ler de ponta a ponta numa tarde e um login sem palavra-passe para expor. O custo dessa escolha é a maturidade: em 19 August 2026, a primeira versão do openGym tinha um mês, enquanto o wger já acumulava anos de versões. Fixe a versão, mantenha os backups e leia as notas de versão antes de cada atualização.

Se ainda está a decidir o que merece espaço no servidor, o que vale a pena alojar por conta própria em 2026 aborda os compromissos envolvidos, e esta aplicação fica bem ao lado de Mealie para receitas ou Actual Budget para finanças no mesmo VPS pequeno.

Atualizar sem perder nada

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

Mude para a versão pretendida com git checkout v<new> e execute docker compose up -d --build para reconstruir os contentores a partir dessa tag. Faça sempre primeiro o backup, porque o processo de restauração dos ficheiros JSON no disco é um único comando tar e demora poucos segundos.

FAQ

Por que o openGym nunca mostra uma solicitação de passkey no meu telefone?

O navegador recusa a criação da credencial porque você está em http:// ou em um endereço IP simples, como http://192.168.1.20:8080. Os navegadores só permitem passkeys em origens HTTPS, com localhost como única exceção. Coloque o openGym atrás de um reverse proxy com um certificado válido para um hostname real, defina RP_ID=gym.example.com e ORIGIN=https://gym.example.com em .env e execute docker compose up -d para que os containers carreguem os novos valores. Se a solicitação aparecer, mas o login informar verification failed, esses dois valores não correspondem exatamente à URL exibida na barra de endereço.

Onde o openGym armazena os meus dados e como faço o backup?

No diretório ./data, ao lado do arquivo compose, montado no container da API como /data. Ele contém db.json para perfis e credenciais públicas de passkey, um state-<uid>.json por usuário para treinos e peso corporal, secret para a chave do cookie de sessão e vapid.json para as chaves de notificações push. Faça o backup com docker compose stop api, depois tar czf ~/opengym-$(date +%F).tar.gz data/, depois docker compose start api e copie o arquivo para fora do servidor. Ignore media/, que contém 140 MB de imagens de exercícios que o job de mídia baixa novamente por conta própria.

O Claude pode ler meu histórico de treinos do openGym?

Sim, por meio do servidor MCP opcional no diretório mcp/. O servidor fixado na v1.2.7 tem oito ferramentas somente leitura. O branch padrão atual tem onze ferramentas: dez rotinas de leitura, incluindo prévias de sessões, planos semanais, treinos, peso corporal, estimativa de uma repetição máxima, equilíbrio muscular e programas; log_workout grava treinos por meio do seu servidor depois do pareamento. Ele não é um container e não abre nenhuma porta: o seu cliente o inicia por stdio, e as ferramentas de leitura acessam diretamente os arquivos JSON em OPENGYM_DATA. Como esse é um caminho do sistema de arquivos, executar o openGym em um VPS exige sincronizar uma cópia de data/ para a máquina que executa o cliente ou chamar o servidor por meio de ssh na configuração do cliente.

Devo hospedar o openGym ou o wger por conta própria?

Escolha o wger se quiser acompanhar alimentação e nutrição junto com o registro de treinos ou se precisar de uma REST API documentada para desenvolver sobre ela. Ele executa uma stack maior: Django sob gunicorn, PostgreSQL, Redis e um worker Celery atrás do nginx. Escolha o openGym se quiser dois containers, arquivos JSON que você pode ler com cat e login com passkey, sem precisar gerenciar senhas. Em 19 August 2026, a primeira release marcada do openGym tinha um mês, portanto consulte um git tag e faça backup de data/ antes de cada atualização.

Este artigo foi útil?