Как развернуть openGym через Docker Compose на VPS
Пошаговое руководство по установке трекера тренировок openGym. Узнайте, как настроить TLS до первого входа, где хранятся данные и как запустить MCP сервер в версии v1.2.7.
Что вы получаете при самостоятельном хостинге openGym
Вы разворачиваете openGym самостоятельно, клонируя репозиторий, редактируя две строки в .env и запуская docker compose up -d --build за обратным прокси-сервером, который выполняет TLS termination (завершение TLS). openGym — это трекер тренировок и веса тела: еженедельные планы, тренировки с инструкциями, запись каждого подхода, отслеживание веса во времени. Проект распространяется по лицензии AGPL-3.0 и хранит все данные в обычных JSON-файлах на диске, поэтому запускать сервер базы данных не требуется.
Стек состоит из двух постоянно работающих контейнеров: контейнера nginx, который отдает сборку React, и контейнера Node, содержащего API. Также используется однократная задача, которая при первом запуске скачивает около 140 МБ изображений и GIF-анимаций упражнений.
Две вещи, которые подразумеваются в README проекта, но не разъяснены для тех, кто развертывает его на публичном сервере. Вход по Passkey привязан к имени хоста, поэтому домен и его сертификат должны существовать до первого входа, а не после. Опциональный сервер MCP в зафиксированной версии v1.2.7 работает только в режиме чтения и запускается на той машине, где работает ваш AI-клиент, а не внутри стека, что меняет порядок действий, когда данные находятся на VPS. Текущий сервер MCP также поддерживает запись тренировок после сопряжения с вашим сервером.
openGym — молодой проект. Первый релиз с тегом, v1.0.0, датирован 20 июля 2026 года, а v1.2.7 вышел 18 августа 2026 года. Тринадцать тегов за первый месяц и 34 к 9 октября 2026 года, когда был выпущен v1.4.0, означают, что приложение активно развивается, поэтому используйте релизный тег, а не собирайте то, что находится в ветке по умолчанию.
Планирование домена до первого входа в систему
Для входа в openGym используются passkeys. Passkey привязан к идентификатору полагающейся стороны (RP ID) — это домен, на котором были созданы учетные данные. Браузеры создают passkeys только по протоколу HTTPS. Единственное исключение — localhost.
Это создает проблему, с которой пользователи сталкиваются при работе с мобильных устройств. Откройте http://203.0.113.10:8080 с другого устройства, и запрос на создание passkey не появится вовсе, так как браузер отказывается создавать учетные данные для источника с обычным HTTP или для прямого IP-адреса. В примечаниях по устранению неполадок проекта указано то же самое: отсутствие запроса означает, что вы используете http:// или IP-адрес.
Более того, RP ID жестко прописан в каждой учетной записи, которую уже зарегистрировали ваши пользователи. Если изменить RP_ID позже, passkeys, сохраненные на их устройствах, перестанут соответствовать домену, и никто не сможет войти в систему. Сначала определите имя хоста, направьте DNS на VPS и настройте сертификат, прежде чем кто-либо нажмет кнопку Create profile.
Развертывание openGym с помощью Docker Compose
Файл compose использует bind-mount для ./data и ./media относительно своего расположения, поэтому каталог, в который вы клонируете репозиторий, и является вашей базой данных. Разместите его в надежном месте.
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В README указан URL для клонирования github.com/DuarteSantos8/openGym. По состоянию на 4 ноября 2026 года этот репозиторий доступен и позиционируется как основной проект. Перед первой сборкой переключитесь на нужный тег: ветка по умолчанию ушла вперед относительно версии, описанной в этом руководстве, и в ней анимации упражнений поставляются внутри образа, а задание по обработке медиафайлов, описанное ниже, больше не существует. В разделе о фиксации версий объясняется, почему это важно.
Отредактируйте .env. На VPS важны три строки.
RP_ID=gym.example.com
ORIGIN=https://gym.example.com
WEB_PORT=127.0.0.1:8080RP_ID — это имя хоста, а ORIGIN — полный URL, включая схему. Они должны в точности совпадать с тем, что введено в адресной строке браузера, иначе вход в систему завершится ошибкой verification failed. Значение WEB_PORT объясняется в разделе о том, как сделать порт 8080 приватным.
docker compose up -d --build
docker compose ps --all
docker compose logs mediadocker compose ps --all должен показать, что web и api запущены, а media завершил работу с кодом 0. Используйте флаг --all: без него Compose выводит только запущенные контейнеры, поэтому завершенное задание media не будет отображаться. Это завершение корректно: задание по обработке медиа имеет статус restart: "no", так как его задача — однократная загрузка. Лог этого задания заканчивается строкой, начинающейся с ✓ Exercise media ready, а ls media/img | wc -l должен вывести 1,324, а не 0; это количество миниатюр, которое поставляется в исходном наборе данных упражнений по состоянию на 9 октября 2026 года. Пустой каталог означает, что загрузка не удалась, и приложение будет отображать карточки упражнений с пустыми изображениями.
Используйте флаг --build. Файл compose с этим тегом ссылается на предварительно собранные образы в ghcr.io с тегом latest. Эти образы были повторно опубликованы 18 октября 2026 года, но latest всегда использует самый свежий релиз, поэтому docker compose pull запустит более новую версию кода, чем та, которую вы только что скачали. Оба сервиса содержат секцию build, а --build выполняет их сборку из ваших локальных исходных файлов. Если Docker Compose для вас в новинку, начните с Docker Compose на VPS и вернитесь сюда позже.
Зафиксируйте версию, так как проект молодой
В реестре снова появились версионированные образы, но файл compose версии v1.2.7 по-прежнему запрашивает latest. По состоянию на 4 ноября 2026 года latest указывает на 1.4.4, выпущенную 3 ноября 2026 года. Вы фиксируете версию через checkout на диске, так как именно это определяет, какая версия приложения попадет в контейнер.
cd /opt/opengym
git fetch --tags
git checkout v1.2.7git status теперь сообщает о состоянии detached HEAD на этом теге, что и требуется для сервера. Ничего не изменится без вашего участия, пока вы не переключитесь на другой тег.
Версия v1.2.7 — это релиз, на основе которого было написано данное руководство, и она больше не является самой новой. Последующие релизы меняют сам процесс развертывания (в ветке по умолчанию задание media удалено), поэтому перед изменением фиксации версии ознакомьтесь с примечаниями к релизу и сравните файл compose. В примечаниях к релизам v1.4.2 и v1.4.3 также сообщается об исправлениях безопасности, и проект рекомендует владельцам self-hosted инсталляций обновиться.
Затем укажите Compose вообще не обращаться к реестру. Добавьте это в docker-compose.override.yml, который Compose загружает автоматически и объединяет с отслеживаемым файлом. Скалярные ключи заменяются значениями из переопределения, поэтому в git ничего менять не нужно, а git pull остается чистым. См. как Compose объединяет файл переопределения для ознакомления с полными правилами слияния.
services:
api:
pull_policy: build
web:
pull_policy: buildПосле этого последующая команда docker compose up -d выполнит сборку из имеющихся у вас исходных кодов, а не будет скачивать то, на что в данный момент указывает latest. Проверьте, что слияние вступило в силу, а затем выполните пересборку на нужном теге.
docker compose config | grep pull_policy
docker compose up -d --buildЗавершение TLS с помощью обратного прокси
Контейнеры используют обычный HTTP. Перед ними должен находиться компонент, который хранит сертификат. Caddy — самый простой путь, так как он самостоятельно запрашивает и обновляет сертификаты от Let's Encrypt.
gym.example.com {
reverse_proxy 127.0.0.1:8080
}nginx, Traefik и Nginx Proxy Manager работают аналогичным образом. То же самое делает Cloudflare Tunnel, который описан в документации проекта и не требует открытия входящих портов.
curl -sI https://gym.example.com | head -1Эта команда должна вернуть HTTP/2 200 без предупреждений о сертификате. Теперь откройте сайт в браузере и нажмите Create profile. Если появляется запрос passkey, а затем при входе отображается verification failed, RP_ID или ORIGIN не совпадает с URL в адресной строке. Исправьте .env и снова выполните docker compose up -d, что пересоздаст контейнеры для считывания новых значений. Команда docker compose restart не перезагружает .env.
Ограничение доступа к порту 8080 из публичной сети
По умолчанию веб-сервис публикует 8080 на всех интерфейсах, поэтому приложение доступно по протоколу HTTP через ваш публичный IP-адрес, в то время как прокси-сервер обслуживает HTTPS на той же машине. Правило межсетевого экрана не решает эту проблему. Docker публикует порт с помощью правила DNAT в таблице nat, и этот трафик затем обрабатывается в цепочке FORWARD, где собственные правила Docker разрешают его, в то время как правила ufw находятся на пути INPUT. Поэтому sudo ufw deny 8080/tcp ничего не блокирует.
Решение заключается в публикации порта только на loopback-адресе. Файл compose выполняет маппинг "${WEB_PORT:-8080}:${NGINX_PORT:-80}", поэтому всё, что вы укажете в WEB_PORT, будет подставлено в левую часть этого маппинга, а краткий синтаксис Docker принимает там пару ip:port. Именно поэтому WEB_PORT=127.0.0.1:8080 работает.
docker compose config
sudo ss -ltnp | grep 8080В объединенной конфигурации, в разделе ports веб-сервиса, вы должны увидеть host_ip: 127.0.0.1. ss должен показывать 127.0.0.1:8080, а не 0.0.0.0:8080. Теперь при попытке подключения с другой машины curl http://<your-vps-ip>:8080 должно выдавать отказ или истечение времени ожидания, в то время как HTTPS-хост продолжит работать.
Закрытие регистрации после создания профиля
Регистрация по умолчанию открыта, а гостевой режим включен. На публичном хосте это означает, что любой, кто узнает URL, сможет создать профиль на вашем сервере. Сначала зарегистрируйте свой собственный профиль, а затем найдите свой ID пользователя: ls data/ выводит список файлов с именем state-<uid>.json для каждого пользователя, и это <uid> является нужным вам значением.
ADMIN_UIDS=<your-uid>
INVITE_ONLY=1
ALLOW_GUEST=0Снова запустите docker compose up -d. В настройках теперь отображается панель администратора (Admin dashboard), где можно создавать и отзывать пригласительные коды, чтобы регистрироваться могли только те, с кем вы тренируетесь, и никто другой. openGym не поддерживает внешние провайдеры идентификации, поэтому эти пригласительные коды управляют только данным приложением и ничем другим на сервере; если вы предпочитаете выдавать одну учетную запись на человека для всех ваших сервисов, использование Authentik в качестве forward auth proxy ограничит доступ к хосту еще до загрузки собственного механизма входа по passkey в openGym.
Где хранятся данные и как работает их резервное копирование
Все данные находятся в каталоге ./data, который примонтирован в контейнер API по пути /data. Существует четыре типа файлов: db.json содержит профили и публичные учетные данные passkey, state-<uid>.json хранит распорядок дня, тренировки и вес одного пользователя, secret — это ключ сессионных cookie, а vapid.json содержит ключи для push-уведомлений, которые генерируются при первом запуске.
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start apiСначала остановите API, чтобы файлы оставались согласованными друг с другом во время копирования с помощью tar. Начиная с версии v1.2.7, API записывает базу данных и JSON с состоянием тренировок во временный файл, а затем атомарно переименовывает его поверх целевого файла, поэтому он не перезаписывает эти файлы «на лету». Затем скопируйте архив с сервера, так как архив, хранящийся на VPS, не переживет выход из строя самого VPS. Исключите media/ из резервной копии: это 140 МБ изображений упражнений, которые медиа-задача при необходимости скачает заново.
Восстановление подразумевает распаковку архива по тому же пути на хосте, обслуживающем тот же домен. Ключ passkey, сохраненный на вашем телефоне, привязан к RP ID, на котором он был создан, поэтому восстановление на новом доменном имени даст вам рабочую базу данных, в которую никто не сможет войти. Сохраняйте домен или будьте готовы к перерегистрации каждого passkey. Тот же принцип применим ко всему остальному, что вы запускаете, а резервное копирование и обновление стека Docker Compose описывает общую процедуру.
Закрепленный MCP-сервер работает в режиме только для чтения на вашей машине
MCP (model context protocol) — это протокол взаимодействия клиента, например Claude Desktop или Cursor, с локальным сервером инструментов. openGym включает такой сервер в mcp/. Он не является частью compose-файла, не запускается в контейнере и не слушает порты. Клиент запускает его как дочерний процесс и обменивается данными через stdio. Закрепленный сервер только читает локальные файлы; текущая версия сервера также отправляет записи о тренировках в ваш подключенный API openGym.
Установите его там, где запущен клиент, а не на сервере:
cd openGym/mcp
npm installЗатем добавьте его в 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 необязателен при установке для одного пользователя, так как сервер автоматически определяет единственный найденный профиль. В текущей ветке по умолчанию доступно одиннадцать инструментов: list_routines, get_routine, preview_session, get_week_plan, list_workouts, get_workout, get_bodyweight, estimate_1rm, muscle_balance, get_programme и log_workout. preview_session показывает, что именно приложение выведет на экран при запуске программы тренировок после того, как политика прогрессии и ваша история изменят план. Версия v1.2.7 включала восемь инструментов только для чтения, без preview_session, get_programme или log_workout. Ассистент, использующий этот закрепленный сервер, может ответить, какой вес вы брали на прошлой неделе, но не может записать подход, изменить программу или что-либо удалить. В текущей ветке десять инструментов работают в режиме чтения, а log_workout сохраняет тренировки через ваш сервер после сопряжения; эта функция отключена до завершения сопряжения. Этот список — компактный пример того, к чему постоянно возвращается проектирование агентов: набор доступных инструментов определяет все возможности модели, а изучение работы агентов через написание цикла самостоятельно — самый быстрый способ понять, почему набор инструментов «только для чтения» является архитектурным решением, а не ограничением.
Вот задача, которую предстоит решить пользователю VPS. OPENGYM_DATA — это путь в файловой системе, а ваши данные находятся на VPS, тогда как AI-клиент запущен на ноутбуке. Есть два честных способа решения.
- Скопируйте данные локально и укажите серверу путь к копии:
rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/, затем установитеOPENGYM_DATAв значение~/opengym-data. Закрепленный сервер только читает данные, поэтому при копировании ничего не теряется. Запускайте rsync повторно, когда потребуются актуальные данные. - Запустите сервер через ssh, установив
commandвssh, аargsв["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Для этого на VPS должен быть установлен Node, а вход в систему не должен выводить ничего в stdout, так как stdout используется для передачи данных протокола.
Оба варианта предполагают, что агент находится на вашем ноутбуке. Если вы хотите, чтобы он работал на той же машине, где лежат данные, OneCLI предоставляет каждому пользователю изолированного агента на сервере, чтобы взаимодействие через stdio с data/ снова стало локальным.
Если cat data/db.json возвращает Permission denied, значит, контейнер API создал эти файлы от имени root, и ваша учетная запись не имеет прав на их чтение. Скопируйте их с помощью sudo или измените владельца файлов на хосте. Для серверов, которые должны слушать сеть, а не stdio, см. запуск MCP-серверов на VPS.
openGym или wger: что выбрать для запуска?
wger — это признанный вариант в данной нише, представляющий собой гораздо более крупное программное обеспечение. Его стек compose включает gunicorn, обслуживающий приложение на Django, PostgreSQL, Redis и воркер Celery за nginx. Взамен вы получаете отслеживание питания и ингредиентов, документированный REST API, обширную базу упражнений сообщества и функции для тренеров, управляющих планами других людей.
openGym состоит из двух контейнеров, папки с JSON-файлами и не требует администрирования учетных записей, кроме использования passkeys. В этом заключается вся разница. Если вам когда-либо приходилось поддерживать работу инсталляции Chatwoot, где резервное копирование означает создание дампа Postgres вместе с директорией загрузок, а каждое обновление версии требует миграции базы данных, вы уже понимаете, каких усилий по обслуживанию требует wger.
Запускайте wger, если хотите отслеживать питание наряду с тренировками или если вам нужен API для разработки. Запускайте openGym, если вам нужен стек, достаточно компактный, чтобы изучить его целиком за один вечер, и вход в систему без паролей, которые можно скомпрометировать. Цена этого выбора — зрелость проекта: по состоянию на 19 августа 2026 года первому релизу openGym всего месяц, в то время как за wger стоят годы обновлений. Фиксируйте версии, делайте резервные копии и читайте примечания к выпуску перед каждым обновлением.
Если вы все еще решаете, что стоит разместить на сервере, статья что стоит хостить самостоятельно в 2026 году описывает все плюсы и минусы, а это приложение отлично соседствует с Mealie для рецептов или Actual Budget для финансов на одном и том же небольшом VPS.
Обновление без потери данных
cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api
git fetch --tagsПереключитесь на нужный релиз с помощью git checkout v<new>, затем выполните docker compose up -d --build, чтобы контейнеры были пересобраны из этого тега. Резервное копирование всегда выполняется в первую очередь, так как восстановление JSON-файлов с диска — это одна команда tar, которая занимает несколько секунд.
FAQ
Почему openGym не запрашивает passkey на моем телефоне?
Браузер отказывается создавать учетные данные, так как вы используете http:// или прямой IP-адрес, например http://192.168.1.20:8080. Браузеры разрешают использование passkey только для HTTPS-источников, за единственным исключением — localhost. Разместите openGym за reverse proxy с действительным сертификатом для реального доменного имени, установите RP_ID=gym.example.com и ORIGIN=https://gym.example.com в .env, а затем выполните docker compose up -d, чтобы контейнеры применили новые значения. Если запрос появляется, но при входе возникает ошибка verification failed, значит, эти два значения не совпадают в точности с URL в адресной строке.
Где openGym хранит мои данные и как их резервировать?
В директории ./data рядом с compose-файлом, которая монтируется в API-контейнер как /data. Там хранятся db.json для профилей и открытых ключей passkey, по одному state-<uid>.json на каждого пользователя для тренировок и веса тела, secret для ключа сессионных cookie и vapid.json для ключей push-уведомлений. Для резервного копирования выполните docker compose stop api, затем tar czf ~/opengym-$(date +%F).tar.gz data/, затем docker compose start api и скопируйте архив с сервера. Пропустите media/: это 140 МБ изображений упражнений, которые media job загружает повторно самостоятельно.
Может ли Claude читать мою историю тренировок в openGym?
Да, через опциональный MCP-сервер в директории mcp/. В зафиксированной версии v1.2.7 сервера есть восемь инструментов только для чтения. В текущей ветке по умолчанию их одиннадцать: десять процедур чтения, предварительный просмотр сессий, недельные планы, тренировки, вес тела, расчетный максимум для одного повторения, мышечный баланс и программы; log_workout записывает тренировки через ваш сервер после сопряжения. Это не контейнер, он не открывает порты: ваш клиент запускает его через stdio, а инструменты чтения обращаются к JSON-файлам по пути OPENGYM_DATA напрямую. Поскольку это путь в файловой системе, при запуске openGym на VPS необходимо либо синхронизировать копию data/ на машину, где запущен клиент, либо вызывать сервер через ssh в конфигурации клиента.
Что выбрать для self-hosting: openGym или wger?
Выбирайте wger, если вам нужно отслеживание питания и калорий помимо журнала тренировок или документированный REST API для разработки. Он использует более крупный стек: Django под управлением gunicorn, PostgreSQL, Redis и Celery worker за nginx. Выбирайте openGym, если вам нужны два контейнера, JSON-файлы, которые можно прочитать с помощью cat, и вход по passkey без необходимости управлять паролями. По состоянию на 19 августа 2026 года первому релизу openGym исполнился один месяц, поэтому используйте git tag и делайте резервную копию data/ перед каждым обновлением.