Jak samodzielnie hostować openGym przez Docker Compose
Wdróż openGym na własnym serwerze VPS. Dowiedz się, jak poprawnie skonfigurować TLS przed użyciem Passkey, gdzie przechowywane są dane JSON i jak uruchomić opcjonalny serwer MCP.
Co otrzymujesz, hostując samodzielnie openGym
Samodzielne hostowanie openGym polega na sklonowaniu repozytorium, edycji dwóch linii w .env oraz uruchomieniu docker compose up -d --build za reverse proxy, które dokonuje terminacji TLS (transport layer security). openGym to narzędzie do śledzenia treningów siłowych i z masą własnego ciała: plany tygodniowe, treningi z przewodnikiem, rejestrowanie każdej serii oraz śledzenie wagi w czasie. Oprogramowanie jest licencjonowane na zasadach AGPL-3.0 i przechowuje wszystkie dane w zwykłych plikach JSON na dysku, więc nie wymaga uruchamiania serwera bazy danych.
Stos technologiczny składa się z dwóch długo działających kontenerów: kontenera nginx, który serwuje kompilację React, oraz kontenera Node, który obsługuje API. Dodatkowo wymagane jest jednorazowe zadanie, które przy pierwszym uruchomieniu pobiera około 140 MB obrazów ćwiczeń i plików GIF.
Istnieją dwie kwestie, które plik README projektu sugeruje, ale nie wyjaśnia wprost w kontekście wdrażania na publicznym serwerze. Logowanie za pomocą Passkey jest powiązane z nazwą hosta, dlatego domena oraz jej certyfikat muszą istnieć przed pierwszym logowaniem, a nie po nim. Opcjonalny serwer MCP w wersji v1.2.7 jest dostępny tylko do odczytu i działa na maszynie, na której uruchomiony jest klient AI, a nie wewnątrz stosu, co zmienia sposób postępowania, gdy dane znajdują się na VPS. Obecny serwer MCP obsługuje również rejestrowanie treningów po sparowaniu z serwerem.
openGym jest młodym projektem. Pierwsze wydanie, v1.0.0, datowane jest na 20 lipca 2026, a wersja v1.2.7 pojawiła się 18 sierpnia 2026. Trzynaście wydań w pierwszym miesiącu i 34 do 9 października 2026, kiedy to ukazała się wersja v1.4.0, oznaczają, że aplikacja jest w fazie intensywnego rozwoju. Z tego powodu należy korzystać z konkretnych tagów wydań, zamiast budować wersję znajdującą się aktualnie w domyślnej gałęzi.
Zaplanuj domenę przed pierwszym logowaniem
Klucze dostępu (passkeys) służą do logowania w openGym. Klucz dostępu jest powiązany z identyfikatorem strony ufającej (RP ID), którym jest domena, na której utworzono poświadczenie. Przeglądarki tworzą klucze dostępu wyłącznie przez HTTPS. Jedynym wyjątkiem jest localhost.
Ma to konsekwencje, z którymi użytkownicy stykają się na urządzeniach mobilnych. Otwarcie http://203.0.113.10:8080 z innego urządzenia nie wywołuje monitu o klucz dostępu, ponieważ przeglądarka odmawia utworzenia poświadczenia w źródle HTTP lub przy użyciu samego adresu IP. Dokumentacja rozwiązywania problemów projektu wskazuje na to samo: brak monitu oznacza, że użytkownik korzysta z http:// lub adresu IP.
Co gorsza, identyfikator RP ID jest trwale zapisany w każdym poświadczeniu zarejestrowanym przez użytkowników. Zmiana RP_ID w późniejszym terminie spowoduje, że klucze dostępu zapisane na urządzeniach przestaną pasować, co uniemożliwi logowanie. Należy najpierw ustalić nazwę hosta, skierować rekordy DNS na VPS i skonfigurować certyfikat, zanim ktokolwiek wybierze opcję utworzenia profilu.
Wdrożenie openGym przy użyciu Docker Compose
Plik compose montuje ./data oraz ./media w trybie bind-mount względem swojej lokalizacji, zatem katalog, do którego pobierasz repozytorium, jest Twoją bazą danych. Umieść go w trwałej lokalizacji.
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 .envPlik README wyświetla adres URL do klonowania github.com/DuarteSantos8/openGym. Według stanu na 4 listopada 2026 r. to repozytorium jest dostępne i określa się jako strona domowa projektu. Przed pierwszym budowaniem sprawdź odpowiedni tag: domyślna gałąź wykracza poza wersję opisaną w tym przewodniku, a w niej animacje ćwiczeń są dostarczane wewnątrz obrazu i poniższe zadanie media już nie istnieje. Sekcja dotycząca przypinania wersji wyjaśnia powody takiego działania.
Edytuj .env. Na serwerze VPS istotne są trzy linie.
RP_ID=gym.example.com
ORIGIN=https://gym.example.com
WEB_PORT=127.0.0.1:8080RP_ID to sama nazwa hosta, a ORIGIN to pełny adres URL wraz ze schematem. Muszą one dokładnie odpowiadać zawartości paska adresu, w przeciwnym razie logowanie zakończy się błędem verification failed. Wartość WEB_PORT została wyjaśniona w sekcji dotyczącej utrzymywania portu 8080 jako prywatnego.
docker compose up -d --build
docker compose ps --all
docker compose logs mediadocker compose ps --all powinno wykazać, że web oraz api działają, a media zakończyło pracę z kodem 0. Zachowaj flagę --all: bez niej Compose wyświetla tylko uruchomione kontenery, więc zakończone zadanie media w ogóle nie będzie widoczne. To zakończenie jest prawidłowe: zadanie media posiada restart: "no", ponieważ jego praca polega na jednorazowym pobraniu danych. Jego dziennik kończy się linią zaczynającą się od ✓ Exercise media ready, a ls media/img | wc -l powinno wyświetlić 1,324 zamiast 0, co odpowiada liczbie miniatur dostarczanych w nadrzędnym zbiorze danych ćwiczeń według stanu na 9 października 2026 r. Pusty katalog oznacza, że pobieranie nie powiodło się, a aplikacja renderuje wtedy karty ćwiczeń z pustymi obrazami.
Zachowaj flagę --build. Plik compose w tym tagu wskazuje na wstępnie zbudowane obrazy w ghcr.io z tagiem latest. Obrazy te zostały ponownie opublikowane 18 października 2026 r., jednak latest podąża za najnowszym wydaniem, więc docker compose pull uruchomiłoby nowszy kod niż ten, który właśnie pobrałeś. Obie usługi posiadają sekcję build, a --build buduje je na podstawie Twojej lokalnej kopii. Jeśli Docker Compose jest dla Ciebie nowością, zacznij od Docker Compose na serwerze VPS i wróć tutaj.
Przypnij wersję, ponieważ ten projekt jest młody
Rejestr ponownie zawiera wersjonowane obrazy, ale plik compose w wersji v1.2.7 nadal odwołuje się do latest. Na dzień 4 listopada 2026 r. latest wskazuje na 1.4.4, wydaną 3 listopada 2026 r. Przypięcie dotyczy checkoutu na dysku, ponieważ to on decyduje, która wersja aplikacji trafi do kontenera.
cd /opt/opengym
git fetch --tags
git checkout v1.2.7git status zgłasza teraz detached HEAD przy tym tagu, co jest pożądanym stanem na serwerze. Nic nie ulegnie zmianie, dopóki nie zostanie wykonany checkout innej wersji.
Wersja v1.2.7 to wydanie, na którym oparto ten przewodnik, i nie jest już ono najnowsze. Późniejsze wydania zmieniają sam proces wdrażania (w domyślnej gałęzi zadanie media zostało usunięte), dlatego przed zmianą przypięcia należy przeczytać informacje o wydaniu i porównać plik compose. Informacje o wydaniach v1.4.2 oraz v1.4.3 wspominają również o poprawkach bezpieczeństwa, a projekt zaleca użytkownikom self-hosted aktualizację.
Następnie należy poinstruować Compose, aby całkowicie przestał korzystać z rejestru. Należy umieścić to w docker-compose.override.yml, który Compose ładuje automatycznie i scala z plikiem śledzonym w repozytorium. Klucze skalarne są zastępowane przez nadpisanie, dzięki czemu nie trzeba edytować plików w git, a git pull pozostaje czyste. Zobacz jak Compose scala plik override, aby poznać pełne zasady scalania.
services:
api:
pull_policy: build
web:
pull_policy: buildPo wprowadzeniu tych zmian, późniejsze polecenie docker compose up -d zbuduje obraz z posiadanych źródeł, zamiast pobierać to, na co w danym dniu wskazuje latest. Sprawdź, czy scalanie przyniosło efekt, a następnie przebuduj obraz przy użyciu tagu.
docker compose config | grep pull_policy
docker compose up -d --buildTerminacja TLS za pomocą reverse proxy
Kontenery komunikują się przy użyciu zwykłego protokołu HTTP. Komponent znajdujący się przed nimi musi obsługiwać certyfikat. Caddy stanowi najkrótszą ścieżkę, ponieważ automatycznie żąda i odnawia certyfikaty z Let's Encrypt.
gym.example.com {
reverse_proxy 127.0.0.1:8080
}nginx, Traefik oraz Nginx Proxy Manager działają w ten sam sposób. Podobnie funkcjonuje Cloudflare Tunnel, który jest opisany w dokumentacji projektu i nie wymaga otwierania żadnych portów przychodzących.
curl -sI https://gym.example.com | head -1Polecenie powinno zwrócić HTTP/2 200 bez ostrzeżenia o certyfikacie. Następnie należy otworzyć witrynę w przeglądarce i wybrać Create profile. Jeśli pojawi się monit o passkey, a po zalogowaniu wystąpi błąd verification failed, RP_ID lub ORIGIN, oznacza to niezgodność z adresem URL w pasku przeglądarki. Należy poprawić .env i ponownie uruchomić docker compose up -d, co spowoduje odtworzenie kontenerów i wczytanie nowych wartości. Polecenie docker compose restart nie przeładowuje .env.
Ograniczenie dostępu do portu 8080 z sieci publicznej
Domyślnie usługa webowa publikuje 8080 na każdym interfejsie, przez co aplikacja jest dostępna przez zwykły protokół HTTP pod publicznym adresem IP, podczas gdy proxy obsługuje HTTPS na tej samej maszynie. Reguła firewalla nie rozwiązuje tego problemu. Docker publikuje port za pomocą reguły DNAT w tablicy nat, a ruch ten jest następnie przetwarzany w łańcuchu FORWARD, gdzie własne reguły Dockera go akceptują, podczas gdy reguły ufw znajdują się na ścieżce INPUT. Z tego powodu sudo ufw deny 8080/tcp nie blokuje żadnego ruchu.
Rozwiązaniem jest publikacja wyłącznie na adresie pętli zwrotnej (loopback). Plik compose mapuje "${WEB_PORT:-8080}:${NGINX_PORT:-80}", więc wartość ustawiona w WEB_PORT jest podstawiana po lewej stronie tego mapowania, a krótka składnia Dockera akceptuje tam parę ip:port. Dlatego WEB_PORT=127.0.0.1:8080 działa poprawnie.
docker compose config
sudo ss -ltnp | grep 8080W scalonej konfiguracji, w sekcji ports usługi webowej, powinna widnieć wartość host_ip: 127.0.0.1. Polecenie ss powinno wykazać 127.0.0.1:8080, a nie 0.0.0.0:8080. Z innej maszyny połączenie przez curl http://<your-vps-ip>:8080 powinno być teraz odrzucane lub kończyć się przekroczeniem czasu oczekiwania, podczas gdy nazwa hosta HTTPS powinna nadal działać.
Zamknięcie rejestracji po utworzeniu profilu
Rejestracja jest domyślnie otwarta, a tryb gościa aktywny. W przypadku publicznego hosta oznacza to, że każda osoba, która trafi na adres URL, może utworzyć profil na serwerze. Najpierw należy zarejestrować własny profil, a następnie odnaleźć swój identyfikator użytkownika: ls data/ wyświetla plik o nazwie state-<uid>.json dla każdego użytkownika, a zawartość tego pliku <uid> jest wartością, która jest potrzebna.
ADMIN_UIDS=<your-uid>
INVITE_ONLY=1
ALLOW_GUEST=0Uruchom ponownie docker compose up -d. W ustawieniach pojawi się teraz panel administratora, w którym można generować i unieważniać kody zaproszeń, dzięki czemu rejestrować mogą się tylko osoby, z którymi trenujesz. openGym nie obsługuje zewnętrznych dostawców tożsamości, więc kody zaproszeń dotyczą wyłącznie tej aplikacji i żadnego innego oprogramowania na serwerze. Jeśli preferowane jest udostępnianie jednego konta na osobę dla wszystkich uruchomionych usług, umieszczenie Authentik jako forward auth proxy zabezpieczy hosta, zanim załaduje się mechanizm logowania passkey w openGym.
Lokalizacja danych i kopia zapasowa zapewniająca ich ochronę
Wszystkie dane znajdują się w katalogu ./data, zamontowanym w kontenerze API w ścieżce /data. Występują cztery rodzaje plików: db.json przechowuje profile oraz publiczne poświadczenia passkey, state-<uid>.json zawiera rutyny, treningi i masę ciała jednego użytkownika, secret to klucz ciasteczek sesyjnych, a vapid.json przechowuje klucze powiadomień push wygenerowane przy pierwszym uruchomieniu.
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start apiNajpierw zatrzymaj API, aby zapewnić spójność plików podczas kopiowania ich przez tar. W wersji v1.2.7 API zapisuje bazę danych oraz plik JSON stanu treningu do pliku tymczasowego, a następnie atomowo zmienia jego nazwę na docelową, dzięki czemu nie nadpisuje tych plików w miejscu podczas ich pracy. Następnie skopiuj archiwum poza serwer, ponieważ archiwum znajdujące się na VPS nie przetrwa awarii samego VPS. Pomiń media/ w kopii zapasowej: to 140 MB obrazów ćwiczeń, które zadanie obsługi mediów pobierze ponownie bez dodatkowych kosztów.
Przywracanie polega na rozpakowaniu archiwum do tej samej ścieżki na hoście obsługującym tę samą domenę. Klucz passkey zapisany w telefonie jest przypisany do identyfikatora RP, dla którego został utworzony, więc przywrócenie danych na nową nazwę hosta spowoduje uzyskanie działającej bazy danych, do której nikt nie będzie mógł się zalogować. Zachowaj domenę lub zaplanuj ponowną rejestrację każdego klucza passkey. Ta sama zasada dotyczy wszystkiego innego, co uruchamiasz, a artykuł tworzenie kopii zapasowych i aktualizacja stosu Docker Compose opisuje ogólną procedurę.
Przypięty serwer MCP jest tylko do odczytu i działa na Twojej maszynie
MCP (model context protocol) to sposób, w jaki klient, taki jak Claude Desktop lub Cursor, komunikuje się z lokalnym serwerem narzędzi. openGym udostępnia jeden z nich w mcp/. Nie jest on częścią pliku compose, nie jest kontenerem i nie nasłuchuje na żadnym porcie. Klient uruchamia go jako proces potomny i komunikuje się z nim przez stdio. Przypięty serwer tylko odczytuje pliki lokalne; bieżący serwer wysyła również zapisy treningów do sparowanego API openGym.
Zainstaluj go tam, gdzie działa klient, a nie na serwerze:
cd openGym/mcp
npm installNastępnie dodaj go do 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 jest opcjonalne w instalacji dla jednego użytkownika, gdzie serwer wykrywa jedyny znaleziony profil. W bieżącej domyślnej gałęzi udostępnia jedenaście narzędzi: list_routines, get_routine, preview_session, get_week_plan, list_workouts, get_workout, get_bodyweight, estimate_1rm, muscle_balance, get_programme oraz log_workout. preview_session pokazuje, co aplikacja faktycznie wyświetli na ekranie po rozpoczęciu rutyny, gdy polityka progresji i Twoja historia nadpiszą plan. Wersja v1.2.7 udostępniała osiem narzędzi tylko do odczytu, bez preview_session, get_programme lub log_workout. Asystent korzystający z tego przypiętego serwera może odpowiedzieć na pytanie, jaki ciężar wyciskałeś w zeszłym tygodniu, ale nie może zarejestrować serii, edytować rutyny ani niczego usunąć. W bieżącej gałęzi dziesięć narzędzi służy do odczytu, a log_workout zapisuje treningi przez Twój serwer po sparowaniu; funkcja ta jest wyłączona do momentu sparowania. Ta lista to zwięzły przykład decyzji projektowej, do której wraca projekt agenta: udostępnione narzędzia stanowią pełen zakres możliwości modelu, a samodzielne napisanie pętli agenta to najszybszy sposób, aby zrozumieć, dlaczego zestaw narzędzi tylko do odczytu jest wyborem projektowym, a nie ograniczeniem.
Oto problem, który musi rozwiązać użytkownik VPS. OPENGYM_DATA to ścieżka w systemie plików, a Twoje dane znajdują się na VPS, podczas gdy klient AI jest na laptopie. Dwie opcje, które uwzględniają ten fakt:
- Skopiuj dane lokalnie i wskaż serwerowi kopię:
rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/, a następnie ustawOPENGYM_DATAna~/opengym-data. Przypięty serwer tylko odczytuje, więc kopia niczego nie traci. Uruchom ponownie rsync, gdy będziesz potrzebować aktualnych danych. - Uruchom serwer przez ssh, z
commandustawionym nasshorazargsustawionym na["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Wymaga to zainstalowanego Node na VPS oraz loginu, który nie wypisuje niczego na stdout, ponieważ stdout jest kanałem protokołu.
Obie opcje zakładają, że sam agent znajduje się na Twoim laptopie. Jeśli wolisz, aby działał na tej samej maszynie co dane, OneCLI zapewnia każdemu użytkownikowi izolowanego agenta na serwerze, dzięki czemu przesył stdio do data/ odbywa się lokalnie.
Jeśli cat data/db.json zwraca Permission denied, kontener API zapisał te pliki jako root i Twój użytkownik nie może ich odczytać. Skopiuj je za pomocą sudo lub zmień właściciela plików na hoście. W przypadku serwerów, które mają nasłuchiwać przez sieć zamiast przez stdio, zobacz uruchamianie serwerów MCP na VPS.
openGym czy wger: co uruchomić?
wger to uznane rozwiązanie w tej niszy, będące znacznie bardziej rozbudowanym oprogramowaniem. Jego stos w Docker Compose obejmuje gunicorn obsługujący aplikację Django, PostgreSQL, Redis oraz worker Celery za serwerem nginx. W zamian otrzymuje się śledzenie odżywiania i składników, udokumentowane API REST, dużą bazę ćwiczeń społecznościowych oraz funkcje dla trenerów zarządzających planami innych osób.
openGym składa się z dwóch kontenerów, folderu plików JSON i nie wymaga administrowania kontami poza passkeys. Na tym polega cała różnica. Jeśli kiedykolwiek utrzymywałeś instalację Chatwoot, gdzie backup oznacza zrzut bazy Postgres wraz z katalogiem plików, a każda aktualizacja wersji wymaga migracji bazy danych, wiesz już, czego pod względem utrzymania wymaga wger.
Uruchom wger, jeśli chcesz śledzić odżywianie obok treningów lub potrzebujesz API do budowania własnych rozwiązań. Uruchom openGym, jeśli potrzebujesz stosu na tyle małego, by przeanalizować go w całości w jedno popołudnie, oraz logowania bez hasła, które mogłoby wyciec. Kosztem tego wyboru jest dojrzałość projektu: na dzień 19 sierpnia 2026 pierwsze wydanie openGym ma miesiąc, podczas gdy wger posiada za sobą lata wydań. Przypinaj wersje, wykonuj kopie zapasowe i czytaj informacje o wydaniu przed każdą aktualizacją.
Jeśli nadal decydujesz, co powinno zająć miejsce na serwerze, co warto hostować samodzielnie w 2026 omawia kompromisy, a ta aplikacja dobrze współgra z Mealie do przepisów lub Actual Budget do finansów na tym samym małym VPS.
Aktualizacja bez utraty danych
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api
git fetch --tagsNależy przełączyć się na wybraną wersję (release) za pomocą git checkout v<new>, a następnie wykonać docker compose up -d --build, aby kontenery zostały przebudowane na podstawie tego tagu. Wykonanie kopii zapasowej jest zawsze priorytetem, ponieważ przywrócenie plików JSON z dysku to tylko jedno polecenie tar, które zajmuje kilka sekund.
FAQ
Dlaczego openGym nigdy nie wyświetla monitu o klucz dostępu (passkey) na moim telefonie?
Przeglądarka odmawia utworzenia poświadczenia, ponieważ użytkownik znajduje się pod adresem http:// lub korzysta z surowego adresu IP, takiego jak http://192.168.1.20:8080. Przeglądarki zezwalają na użycie kluczy dostępu tylko w źródłach HTTPS, z wyjątkiem localhost. Należy umieścić openGym za odwrotnym proxy posiadającym prawidłowy certyfikat dla rzeczywistej nazwy hosta, ustawić RP_ID=gym.example.com oraz ORIGIN=https://gym.example.com w pliku .env, a następnie uruchomić docker compose up -d, aby kontenery pobrały nowe wartości. Jeśli monit się pojawia, ale logowanie zgłasza verification failed, oznacza to, że te dwie wartości nie odpowiadają dokładnie adresowi URL w pasku przeglądarki.
Gdzie openGym przechowuje moje dane i jak wykonać ich kopię zapasową?
W katalogu ./data obok pliku compose, zamontowanym w kontenerze API jako /data. Zawiera on db.json dla profili i publicznych poświadczeń kluczy dostępu, po jednym state-<uid>.json na użytkownika dla treningów i masy ciała, secret dla klucza ciasteczek sesji oraz vapid.json dla kluczy powiadomień push. Należy wykonać kopię zapasową za pomocą docker compose stop api, następnie tar czf ~/opengym-$(date +%F).tar.gz data/, potem docker compose start api i skopiować archiwum z serwera. Można pominąć media/, który zawiera 140 MB obrazów ćwiczeń, pobieranych ponownie automatycznie przez zadanie obsługi mediów.
Czy Claude może odczytać moją historię treningów w openGym?
Tak, poprzez opcjonalny serwer MCP w katalogu mcp/. Przypięta wersja serwera v1.2.7 posiada osiem narzędzi tylko do odczytu. Bieżąca domyślna gałąź zawiera jedenaście narzędzi: dziesięć procedur odczytu, podglądy sesji, plany tygodniowe, treningi, masę ciała, szacowany ciężar maksymalny (1RM), balans mięśniowy i programy; log_workout zapisuje treningi przez serwer po sparowaniu. Nie jest to kontener i nie otwiera żadnego portu: klient uruchamia go przez stdio, a narzędzia odczytu uzyskują bezpośredni dostęp do plików JSON w OPENGYM_DATA. Ponieważ jest to ścieżka w systemie plików, uruchomienie openGym na VPS oznacza konieczność synchronizacji kopii data/ na maszynę, na której działa klient, lub wywołanie serwera przez ssh z poziomu konfiguracji klienta.
Czy powinienem hostować samodzielnie openGym czy wger?
Należy wybrać wger, jeśli wymagane jest śledzenie żywienia i diety obok dziennika treningowego lub udokumentowane API REST do dalszej rozbudowy. Aplikacja ta uruchamia większy stos: Django pod gunicorn, PostgreSQL, Redis oraz worker Celery za nginx. Należy wybrać openGym, jeśli wymagane są dwa kontenery, pliki JSON możliwe do odczytania za pomocą cat oraz logowanie kluczem dostępu bez konieczności zarządzania hasłem. Według stanu na 19 sierpnia 2026, pierwsze oznaczone wydanie openGym ma miesiąc, dlatego należy sprawdzać tagi git i tworzyć kopię zapasową data/ przed każdą aktualizacją.