SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-11-06

Come fare il self-hosting di openGym con Docker

Guida al deploy di openGym su VPS con Docker Compose: tag git fissato, TLS prima della prima passkey, dati in file JSON e server MCP opzionale.

Cosa si ottiene con il self-hosting di openGym

Il self-hosting di openGym consiste nel clonare il repository, modificare due righe in .env ed eseguire docker compose up -d --build dietro un reverse proxy con terminazione TLS (transport layer security). openGym è un tracker per palestra e peso corporeo: piani settimanali, allenamenti guidati, registrazione di ogni serie e andamento del peso nel tempo. È distribuito con licenza AGPL-3.0 e memorizza tutto in file JSON non cifrati sul disco, quindi non è necessario eseguire un database server.

Lo stack è composto da due container a esecuzione prolungata: un container nginx che pubblica la build React e un container Node che contiene l'API. Include inoltre un job eseguito una sola volta, che al primo avvio scarica circa 140 MB di immagini e GIF di esercizi.

Il README del progetto lascia intendere due aspetti senza descriverli esplicitamente per chi esegue il deployment su un server pubblico. L'accesso con passkey è associato a un hostname, quindi il dominio e il relativo certificato devono esistere prima del primo accesso, non dopo. Inoltre, il server MCP opzionale è in sola lettura nel tag v1.2.7 fissato e viene eseguito sul computer in cui gira il client AI, non all'interno dello stack. Questo modifica le operazioni necessarie quando i dati risiedono su un VPS. Il server MCP attuale supporta anche la registrazione degli allenamenti dopo l'abbinamento al server.

openGym è un progetto giovane. La prima release contrassegnata, v1.0.0, è datata 20 July 2026, mentre v1.2.7 è stata pubblicata il 18 August 2026. Tredici tag nel primo mese e 34 al 9 October 2026, con v1.4.0 contrassegnata in quella data, indicano che l'applicazione è ancora in rapida evoluzione. Per questo, esegui il checkout di un tag di release invece di compilare il contenuto disponibile in quel momento sul branch predefinito.

Pianificare il dominio prima del primo accesso

Le passkey sono il metodo con cui si accede a openGym. Una passkey è associata a un relying party ID (RP ID), cioè al dominio sul quale è stata creata la credenziale, e i browser creano passkey soltanto tramite HTTPS. L'unica eccezione è localhost.

Questo comporta un problema che si manifesta quando si usa un altro dispositivo. Apri http://203.0.113.10:8080 da un altro dispositivo e non viene visualizzata alcuna richiesta di creazione della passkey, perché il browser rifiuta di creare una credenziale su un'origine HTTP semplice o su un indirizzo IP senza nome DNS. Anche le note per la risoluzione dei problemi del progetto indicano la stessa causa: se la richiesta non viene visualizzata, stai usando http:// oppure un indirizzo IP.

La situazione è più critica perché l'RP ID è incorporato in ogni credenziale già registrata dagli utenti. Se in seguito cambi RP_ID, le passkey memorizzate sui loro dispositivi non corrisponderanno più e nessuno potrà accedere. Scegli prima il nome host, configura il DNS per puntare al VPS e verifica il funzionamento del certificato prima che qualcuno tocchi Create profile.

Implementare openGym con Docker Compose

Il file Compose monta con bind ./data e ./media in relazione alla propria posizione, quindi la directory in cui esegui il clone è il database dell'applicazione. Scegli una posizione 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

Il README riporta un URL di clone github.com/DuarteSantos8/openGym. Al 4 novembre 2026, il repository è raggiungibile e si presenta come sede del progetto. Esegui il checkout del tag prima della prima build: il branch predefinito è andato oltre la versione descritta in questa guida. In quel branch le animazioni degli esercizi sono incluse nell'immagine e il job multimediale descritto sotto non esiste più. La sezione sul pinning spiega il motivo.

Modifica .env. Su un VPS sono importanti tre righe.

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

RP_ID è il nome host senza altro, mentre ORIGIN è l'URL completo, incluso lo schema. Devono corrispondere esattamente all'indirizzo visualizzato nella barra del browser, altrimenti l'accesso non riesce con verification failed. Il valore WEB_PORT è spiegato nella sezione su come mantenere privata la porta 8080.

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

docker compose ps --all dovrebbe mostrare web e api in esecuzione e media terminato con codice 0. Mantieni il flag --all: senza questo flag, Compose elenca soltanto i container in esecuzione, quindi il job media completato non viene visualizzato. La terminazione è corretta: il job multimediale ha restart: "no" perché esegue un download una tantum. Il relativo log termina con una riga che inizia con ✓ Exercise media ready e ls media/img | wc -l dovrebbe restituire 1,324 invece di 0. Questo è il numero di miniature incluse nel dataset di esercizi upstream al 9 ottobre 2026. Una directory vuota indica che il download non è riuscito; in questo caso l'applicazione visualizza le schede degli esercizi senza immagini.

Mantieni il flag --build. Il file Compose di questo tag specifica immagini precompilate su ghcr.io con il tag latest. Queste immagini sono state nuovamente pubblicate al 18 ottobre 2026, ma latest segue la release più recente; di conseguenza, docker compose pull eseguirebbe codice più recente rispetto al sorgente di cui hai appena eseguito il checkout. Entrambi i servizi includono una sezione build e --build li compila invece a partire dal checkout locale. Se Compose è una novità per te, inizia da Docker Compose su un VPS e poi torna qui.

Bloccare la versione, perché questo progetto è giovane

Il registry contiene di nuovo immagini versionate, ma il file Compose alla versione v1.2.7 richiede ancora latest. Al 4 novembre 2026, latest punta a 1.4.4, rilasciata il 3 novembre 2026. Il valore da bloccare è il checkout presente sul disco, perché determina quale versione dell'applicazione viene inserita nel container.

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

git status ora restituisce un HEAD scollegato su quel tag, che è il comportamento desiderato su un server. Nulla cambia finché non esegui il checkout di un altro tag.

v1.2.7 è la release utilizzata come riferimento per questa guida e non è più la più recente. Le release successive modificano anche il deployment (sul branch predefinito il job dei media non è più presente), quindi leggi le release note e confronta il file Compose prima di spostare il pin. Le release note delle versioni v1.4.2 e v1.4.3 riportano inoltre correzioni di sicurezza e il progetto chiede agli utenti che gestiscono autonomamente l'hosting di aggiornare.

Ora configura Compose in modo che smetta del tutto di cercare immagini nel registry. Inserisci questo contenuto in docker-compose.override.yml, che Compose carica automaticamente e applica sopra al file tracciato. Le chiavi scalari vengono sostituite dal file di override, quindi non è necessario modificare nulla in git e git pull rimane pulito. Consulta come Compose unisce un file di override per le regole complete di merge.

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

Con questa configurazione, un successivo docker compose up -d esegue la build a partire dal codice sorgente disponibile localmente, invece di effettuare il pull di qualunque versione indichi latest in quel momento. Verifica che il merge sia stato applicato, quindi ricrea l'immagine usando il tag.

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

Terminare TLS con un reverse proxy

I container usano HTTP in chiaro. Un componente a monte deve gestire il certificato. Caddy è la soluzione più rapida, perché richiede e rinnova autonomamente il certificato tramite Let's Encrypt.

gym.example.com {
    reverse_proxy 127.0.0.1:8080
}

nginx, Traefik e Nginx Proxy Manager funzionano allo stesso modo. Lo stesso vale per Cloudflare Tunnel, documentato dal progetto, che non richiede alcuna porta in ingresso aperta.

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

Il comando dovrebbe restituire HTTP/2 200 senza avvisi relativi al certificato. Ora apri il sito in un browser e fai clic su Create profile. Se viene visualizzata la richiesta della passkey e l'accesso restituisce un errore, verification failed, RP_ID o ORIGIN non corrisponde all'URL nella barra degli indirizzi. Correggi .env ed esegui nuovamente docker compose up -d: in questo modo i container vengono ricreati e leggono i nuovi valori. Un docker compose restart non ricarica .env.

Mantieni la porta 8080 non esposta a Internet

Per impostazione predefinita, il servizio web pubblica 8080 su ogni interfaccia. L'applicazione è quindi raggiungibile tramite HTTP non cifrato sull'IP pubblico, mentre il proxy gestisce HTTPS sullo stesso server. Una regola del firewall non risolve il problema. Docker pubblica una porta con una regola DNAT nella tabella nat, quindi il traffico viene gestito nella catena FORWARD, dove le regole proprie di Docker lo accettano. Le regole di ufw si trovano invece nel percorso INPUT. sudo ufw deny 8080/tcp non blocca quindi alcun traffico.

La soluzione consiste nel pubblicare la porta solo sull'indirizzo di loopback. Il file Compose mappa "${WEB_PORT:-8080}:${NGINX_PORT:-80}". Qualunque valore imposti in WEB_PORT viene sostituito a sinistra di questa mappatura, e la sintassi breve di Docker accetta una coppia ip:port in quella posizione. Per questo WEB_PORT=127.0.0.1:8080 funziona.

docker compose config
sudo ss -ltnp | grep 8080

Nella configurazione risultante, sotto ports del servizio web, devi vedere host_ip: 127.0.0.1. ss dovrebbe mostrare 127.0.0.1:8080 e non 0.0.0.0:8080. Da un'altra macchina, curl http://<your-vps-ip>:8080 dovrebbe ora essere rifiutato o andare in timeout, mentre il nome host HTTPS continua a funzionare.

Chiudere le registrazioni dopo aver creato il proprio profilo

La registrazione è aperta per impostazione predefinita e la modalità guest è attiva. Su un hostname pubblico, chiunque trovi l'URL può creare un profilo sul server. Registrate prima il vostro profilo, quindi individuate il vostro ID utente: ls data/ elenca un file denominato state-<uid>.json per ogni utente e quel <uid> è il valore necessario.

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

Eseguite di nuovo docker compose up -d. In Settings viene ora visualizzato un pannello Admin in cui potete generare e revocare i codici di invito, consentendo alle persone con cui vi allenate di registrarsi e impedendo la registrazione a chiunque altro. openGym non supporta i provider di identità esterni, quindi questi codici di invito controllano solo questa applicazione e nient'altro sul server; se preferite assegnare un unico account per persona a tutti i servizi che eseguite, configurare Authentik come proxy forward auth protegge l'hostname prima che venga caricata la procedura di accesso con passkey integrata in openGym.

Dove risiedono i dati e il backup che li protegge

Tutto si trova nella directory ./data, montata nel container API in /data. Esistono quattro tipi di file: db.json contiene i profili e le credenziali pubbliche delle passkey, state-<uid>.json contiene le routine, gli allenamenti e il peso corporeo di un utente, secret è la chiave dei cookie di sessione e vapid.json contiene le chiavi per le notifiche push generate al primo avvio.

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

Arrestare prima l'API, in modo che i file restino coerenti tra loro mentre tar li copia. Nella versione v1.2.7, l'API scrive il database e il JSON dello stato degli allenamenti in un file temporaneo e lo rinomina in modo atomico sovrascrivendo la destinazione. Non riscrive quindi questi file attivi direttamente. Copiare poi l'archivio fuori dal server, perché un archivio che rimane sul VPS non sopravvive alla perdita del VPS. Escludere media/ dal backup: contiene 140 MB di immagini degli esercizi che il job multimediale scarica nuovamente senza costi.

Per ripristinare i dati, estrarre l'archivio nello stesso percorso su un host che espone lo stesso dominio. Una passkey salvata sul telefono è associata al RP ID con cui è stata creata. Un ripristino su un nuovo hostname fornisce quindi un database funzionante, ma nessuno può accedervi. Mantenere il dominio oppure prevedere di registrare nuovamente ogni passkey. La stessa procedura si applica a tutto ciò che si esegue; backup e aggiornamento di uno stack Docker Compose descrive la procedura generale.

Il server MCP bloccato è di sola lettura e viene eseguito sul tuo computer

MCP (model context protocol) è il protocollo con cui un client come Claude Desktop o Cursor comunica con un server di strumenti locale. openGym ne include uno in mcp/. Non fa parte del file compose, non è un container e non è in ascolto su alcuna porta. Il client lo avvia come processo figlio e comunica con esso tramite stdio. Il server bloccato legge soltanto i file locali; il server corrente invia anche le modifiche agli allenamenti all'API openGym associata.

Installalo nel sistema in cui viene eseguito il client, non sul server:

cd openGym/mcp
npm install

Poi aggiungilo 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 è facoltativo in un'installazione per un singolo utente, in cui il server rileva l'unico profilo trovato. Nel branch predefinito corrente espone undici strumenti: 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 ciò che l'app visualizzerà effettivamente quando avvii una routine, dopo che la policy di progressione e la cronologia hanno modificato il piano. Il tag v1.2.7 includeva otto strumenti di sola lettura, senza preview_session, get_programme o log_workout. Un assistente che usa quel server bloccato può rispondere a cosa hai allenato la settimana scorsa, ma non può registrare una serie, modificare una routine o eliminare dati. Nel branch corrente, dieci strumenti leggono e log_workout salva gli allenamenti tramite il tuo server dopo l'associazione; resta disabilitato finché non viene associato. Questo elenco è un esempio sintetico della decisione progettuale che ricorre nella progettazione degli agenti: gli strumenti esposti definiscono tutto ciò che un modello può fare e imparare come funzionano gli agenti scrivendo personalmente il ciclo è il modo più rapido per capire perché un insieme di strumenti di sola lettura sia una scelta progettuale, non una limitazione.

Questo è il problema che un utente di un VPS deve risolvere. OPENGYM_DATA è un percorso del filesystem, mentre i dati si trovano sul VPS e il client AI sul laptop. Esistono due opzioni coerenti con questa situazione.

  1. Copia i dati sul laptop e configura il server per usare la copia: rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/, quindi imposta OPENGYM_DATA su ~/opengym-data. Il server bloccato esegue soltanto letture, quindi la copia non comporta perdite. Esegui nuovamente rsync quando vuoi dati aggiornati.
  2. Esegui il server tramite SSH, con command impostato su ssh e args impostato su ["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Questa soluzione richiede che Node sia installato sul VPS e che l'accesso SSH non stampi nulla su stdout, perché stdout è il canale del protocollo.

Entrambe le opzioni presuppongono che l'agente venga eseguito sul laptop. Se invece preferisci eseguirlo sullo stesso sistema dei dati, OneCLI fornisce a ogni utente un agente isolato in una sandbox sul server, così il collegamento stdio verso data/ torna a essere locale.

Se cat data/db.json restituisce Permission denied, il container API ha scritto quei file come root e il tuo account non può leggerli. Copiali con sudo oppure modifica la proprietà sul sistema host. Per i server che devono essere raggiungibili in rete invece di comunicare tramite stdio, consulta eseguire server MCP su un VPS.

openGym o wger: quale dovresti eseguire?

wger è la soluzione consolidata in questo ambito ed è un software molto più complesso. Il relativo stack Compose esegue gunicorn per servire un'applicazione Django, PostgreSQL, Redis e un worker Celery dietro nginx. In cambio offre il monitoraggio dell'alimentazione e degli ingredienti, un'API REST documentata, un ampio database di esercizi e funzioni per i trainer che gestiscono i piani di altre persone.

openGym è composto da due container, una directory di file JSON e nessun account da amministrare oltre alle passkey. Questa è l'intera differenza. Se hai già mantenuto in esecuzione un'installazione di Chatwoot, dove un backup consiste in un dump di Postgres insieme alla directory degli upload e ogni aggiornamento di versione esegue migrazioni del database, sai già quale impegno di manutenzione richiede la struttura di wger.

Esegui wger se vuoi monitorare l'alimentazione insieme all'allenamento o se ti serve un'API su cui sviluppare. Esegui openGym se vuoi uno stack abbastanza piccolo da poter essere letto dall'inizio alla fine in un pomeriggio e un accesso senza password da sottrarre. Il costo di questa scelta è la maturità: al 19 agosto 2026 la prima release di openGym risale a un mese fa, mentre wger ha alle spalle anni di release. Fissa la versione, conserva i backup e leggi le note di rilascio prima di ogni aggiornamento.

Se stai ancora decidendo cosa merita spazio sul server, cosa vale la pena self-hostare nel 2026 illustra i compromessi; questa applicazione si affianca bene a Mealie per le ricette o Actual Budget per il denaro sullo stesso VPS di piccole dimensioni.

Aggiornare senza perdere dati

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

Seleziona la release desiderata con git checkout v<new>, quindi esegui docker compose up -d --build per ricostruire i container a partire da quel tag. Esegui sempre prima il backup, perché il ripristino dei file JSON presenti su disco richiede un solo comando tar e richiede pochi secondi.

FAQ

Perché openGym non mostra mai una richiesta di passkey sul telefono?

Il browser rifiuta di creare una credenziale perché stai usando http:// oppure un indirizzo IP diretto, ad esempio http://192.168.1.20:8080. I browser consentono le passkey soltanto su origini HTTPS, con localhost come unica eccezione. Pubblica openGym dietro un reverse proxy con un certificato valido per un hostname reale, imposta RP_ID=gym.example.com e ORIGIN=https://gym.example.com in .env ed esegui docker compose up -d, in modo che i container acquisiscano i nuovi valori. Se compare la richiesta ma l'accesso restituisce verification failed, i due valori non corrispondono esattamente all'URL mostrato nella barra degli indirizzi.

Dove memorizza i dati openGym e come posso eseguirne il backup?

Nella directory ./data accanto al file compose, montata nel container API come /data. Contiene db.json per i profili e le credenziali passkey pubbliche, un file state-<uid>.json per ogni utente con gli allenamenti e il peso corporeo, secret per la chiave dei cookie di sessione e vapid.json per le chiavi delle notifiche push. Esegui il backup con docker compose stop api, poi tar czf ~/opengym-$(date +%F).tar.gz data/ e infine docker compose start api, quindi copia l'archivio fuori dal server. Escludi media/, che contiene 140 MB di immagini degli esercizi e viene scaricato nuovamente dal job dei media.

Claude può leggere la cronologia degli allenamenti di openGym?

Sì, tramite il server MCP opzionale nella directory mcp/. Il server bloccato alla versione v1.2.7 dispone di otto strumenti in sola lettura. Il branch predefinito corrente dispone di undici strumenti: dieci routine di lettura, anteprime delle sessioni, piani settimanali, allenamenti, peso corporeo, stima del massimale per una ripetizione, bilanciamento muscolare e programmi; log_workout scrive gli allenamenti tramite il server dopo l'associazione. Non è un container e non apre porte: il client lo avvia tramite stdio e i relativi strumenti di lettura accedono direttamente ai file JSON in OPENGYM_DATA. Poiché si tratta di un percorso del filesystem, se openGym viene eseguito su un VPS devi sincronizzare una copia di data/ sul computer che esegue il client oppure richiamare il server tramite ssh dalla configurazione del client.

Devo self-hostare openGym o wger?

Scegli wger se vuoi affiancare il monitoraggio di alimentazione e nutrizione al registro degli allenamenti oppure se ti serve una REST API documentata su cui sviluppare. Utilizza uno stack più ampio: Django tramite gunicorn, PostgreSQL, Redis e un worker Celery dietro nginx. Scegli openGym se vuoi due container, file JSON leggibili con cat e un accesso tramite passkey senza dover gestire password. Al 19 agosto 2026, la prima release con tag di openGym ha un mese di vita; quindi esegui il checkout di un tag git ed esegui il backup di data/ prima di ogni aggiornamento.

Questo articolo ti è stato utile?