SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor · Cập nhật ngày 2026-11-06

Tự host openGym bằng Docker Compose trên VPS

Triển khai openGym trên VPS với Docker Compose: ghim git tag, bật TLS trước passkey đầu tiên, biết dữ liệu nằm ở đâu và dùng MCP server tùy chọn.

Bạn nhận được gì khi tự host openGym

Bạn tự host openGym bằng cách clone repository, sửa 2 dòng trong .env rồi chạy docker compose up -d --build phía sau reverse proxy thực hiện TLS termination (bảo mật lớp truyền tải). openGym là ứng dụng theo dõi việc tập gym và cân nặng: kế hoạch hằng tuần, bài tập có hướng dẫn, ghi lại mọi set và theo dõi cân nặng theo thời gian. Ứng dụng được cấp phép theo AGPL-3.0 và lưu mọi dữ liệu trong các file JSON thuần trên disk, nên bạn không cần chạy database server.

Stack gồm 2 container chạy lâu dài: một container nginx phục vụ bản build React và một container Node chứa API; ngoài ra còn có một job chạy một lần để tải khoảng 140 MB ảnh và GIF bài tập trong lần khởi động đầu tiên.

README của dự án ngầm cho biết 2 điểm nhưng không nói rõ cho người triển khai trên public server. Đăng nhập bằng passkey gắn với hostname, nên domain và certificate phải tồn tại trước lần đăng nhập đầu tiên, không phải sau đó. MCP server tùy chọn ở tag v1.2.7 được giới hạn chỉ đọc và chạy trên máy nơi AI client của bạn chạy, không chạy bên trong stack. Điều này làm thay đổi các bước cần thực hiện khi dữ liệu nằm trên VPS. MCP server hiện tại cũng hỗ trợ ghi lại buổi tập sau khi pair với server của bạn.

openGym vẫn còn mới. Bản release đầu tiên được tag, v1.0.0, có ngày 20 July 2026, còn v1.2.7 được phát hành vào 18 August 2026. Có 13 tag trong tháng đầu tiên và 34 tag tính đến 9 October 2026, với v1.4.0 được tag vào cùng ngày. Điều này cho thấy ứng dụng vẫn đang được phát triển nhanh, vì vậy hãy checkout một release tag thay vì build phiên bản hiện có trên default branch.

Lên kế hoạch cho domain trước lần đăng nhập đầu tiên

Passkey là cách bạn đăng nhập vào openGym. Một passkey được gắn với một relying party ID (RP ID), chính là domain nơi credential được tạo, và trình duyệt chỉ tạo passkey qua HTTPS. Ngoại lệ duy nhất là localhost.

Điều này dẫn đến một hệ quả mà người dùng thường gặp trên điện thoại. Mở http://203.0.113.10:8080 từ một thiết bị khác và không thấy prompt passkey nào xuất hiện, vì trình duyệt từ chối tạo credential trên origin HTTP thuần hoặc địa chỉ IP trần. Các ghi chú khắc phục sự cố của dự án cũng nêu rõ: không có prompt nghĩa là bạn đang ở trên http:// hoặc đang dùng IP.

Tệ hơn nữa, RP ID được gắn cứng vào mọi credential mà người dùng đã đăng ký. Nếu thay đổi RP_ID sau này, các passkey lưu trên thiết bị của họ sẽ không còn khớp, dẫn đến việc không ai có thể đăng nhập. Hãy quyết định hostname trước, trỏ DNS về VPS và thiết lập chứng chỉ hoạt động ổn định trước khi bất kỳ ai nhấn Create profile.

Triển khai openGym bằng Docker Compose

File compose bind-mount ./data và ./media theo đường dẫn tương đối với chính file đó, nên thư mục bạn clone vào chính là database. Hãy đặt thư mục này ở nơi lưu trữ bền vững.

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 cung cấp một URL clone github.com/DuarteSantos8/openGym. Tính đến ngày 4 November 2026, repository đó vẫn truy cập được và tự mô tả là trang chính của project. Hãy checkout tag trước lần build đầu tiên: branch mặc định đã vượt qua phiên bản được mô tả trong hướng dẫn này. Ở branch đó, animation của bài tập đã được đóng gói trong image và media job bên dưới không còn tồn tại. Phần nói về pinning giải thích lý do.

Chỉnh sửa .env. Trên VPS, có 3 dòng cần chú ý.

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

RP_ID là hostname không có phần còn lại của URL, còn ORIGIN là URL đầy đủ gồm cả scheme. Hai giá trị này phải khớp chính xác với địa chỉ trên thanh địa chỉ, nếu không đăng nhập sẽ thất bại với verification failed. Giá trị WEB_PORT được giải thích trong phần giữ port 8080 ở chế độ private.

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

docker compose ps --all phải hiển thị web và api đang chạy, còn media phải ở trạng thái exited với code 0. Hãy giữ flag --all: nếu thiếu flag này, Compose chỉ liệt kê các container đang chạy, nên job media đã hoàn tất sẽ hoàn toàn không xuất hiện. Trạng thái exit đó là đúng: media job đã restart: "no" vì công việc của nó là tải xuống một lần. Log của job kết thúc bằng một dòng bắt đầu với ✓ Exercise media ready, và ls media/img | wc -l phải in ra 1,324 thay vì 0. Đây là số thumbnail mà dataset bài tập upstream cung cấp tính đến ngày 9 October 2026. Thư mục rỗng nghĩa là việc tải xuống thất bại; khi đó app sẽ hiển thị các thẻ bài tập với ảnh trống.

Hãy giữ flag --build. File compose ở tag này chỉ định các image dựng sẵn trên ghcr.io với tag latest. Các image đó được publish lại tính đến ngày 18 October 2026, nhưng latest theo release mới nhất, nên docker compose pull sẽ chạy code mới hơn source bạn vừa checkout. Cả hai service đều có section build, và --build sẽ build chúng từ checkout của bạn. Nếu bạn chưa quen với Compose, hãy bắt đầu từ Docker Compose trên VPS rồi quay lại.

Ghim phiên bản vì project này còn mới

Registry hiện đã có lại các image theo phiên bản, nhưng file compose ở v1.2.7 vẫn yêu cầu latest. Tính đến ngày 4 November 2026, latest trỏ đến 1.4.4, được phát hành ngày 3 November 2026. Phiên bản bạn ghim là checkout trên disk, vì nó quyết định phiên bản application nào sẽ nằm trong container.

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

git status hiện báo HEAD detached tại tag đó. Đây là trạng thái phù hợp trên server. Mã nguồn sẽ không tự chuyển sang phiên bản khác cho đến khi bạn checkout một phiên bản khác.

v1.2.7 là release được dùng khi viết hướng dẫn này và hiện không còn là phiên bản mới nhất. Các release sau thay đổi cả deployment (trên branch mặc định, media job đã bị xóa), vì vậy hãy đọc release notes và so sánh file compose trước khi thay đổi phiên bản ghim. Release notes của v1.4.2 và v1.4.3 cũng nêu các bản sửa lỗi bảo mật, và project yêu cầu người tự host cập nhật.

Tiếp theo, hãy cấu hình Compose không truy cập registry nữa. Đặt nội dung này vào docker-compose.override.yml. Compose tự động load file này và merge nó lên trên file đang được theo dõi. Các scalar key sẽ bị override thay thế, nên không cần sửa gì trong git và git pull vẫn sạch. Xem cách Compose merge file override để biết đầy đủ các quy tắc merge.

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

Sau khi cấu hình xong, lần docker compose up -d tiếp theo sẽ build từ source hiện có thay vì pull phiên bản mà latest trỏ đến vào ngày đó. Kiểm tra việc merge đã có hiệu lực, rồi build lại tại tag này.

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

Kết thúc TLS bằng reverse proxy

Các container chỉ giao tiếp qua HTTP thuần. Cần một thành phần đứng trước để giữ chứng chỉ. Caddy là cách nhanh nhất vì nó tự yêu cầu và gia hạn chứng chỉ từ Let's Encrypt.

gym.example.com {
    reverse_proxy 127.0.0.1:8080
}

nginx, Traefik và Nginx Proxy Manager đều hoạt động theo cách tương tự. Cloudflare Tunnel cũng vậy, phương thức này đã được tài liệu dự án đề cập và không yêu cầu mở bất kỳ cổng inbound nào.

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

Lệnh đó sẽ trả về HTTP/2 200 mà không có cảnh báo chứng chỉ. Bây giờ hãy mở trang web trên trình duyệt và nhấn Create profile. Nếu prompt passkey xuất hiện và sau đó quá trình đăng nhập báo verification failed, RP_ID hoặc ORIGIN không khớp với URL trên thanh địa chỉ. Hãy sửa .env và chạy lại docker compose up -d, lệnh này sẽ tạo lại các container để chúng đọc các giá trị mới. Một lệnh docker compose restart không tải lại .env.

Giữ cổng 8080 không public ra Internet

Theo mặc định, web service publish 8080 trên mọi interface, vì vậy ứng dụng có thể truy cập qua HTTP thường tại IP public của bạn trong khi proxy phục vụ HTTPS trên cùng máy chủ. Một rule firewall không giải quyết được vấn đề này. Docker publish cổng bằng rule DNAT trong bảng nat, và lưu lượng đó sau đó được xử lý trong chain FORWARD nơi các rule của Docker chấp nhận nó, trong khi các rule của ufw nằm trên đường dẫn INPUT. Do đó, sudo ufw deny 8080/tcp không chặn được gì cả.

Cách khắc phục là chỉ publish trên địa chỉ loopback. File compose map "${WEB_PORT:-8080}:${NGINX_PORT:-80}", vì vậy bất cứ thứ gì bạn đặt trong WEB_PORT sẽ được thay thế vào bên trái của mapping đó, và cú pháp rút gọn của Docker chấp nhận cặp ip:port ở đó. Đó là lý do tại sao WEB_PORT=127.0.0.1:8080 hoạt động.

docker compose config
sudo ss -ltnp | grep 8080

Trong cấu hình đã merge, bên dưới ports của web service, bạn cần thấy host_ip: 127.0.0.1. ss sẽ hiển thị 127.0.0.1:8080 chứ không phải 0.0.0.0:8080. Từ một máy khác, curl http://<your-vps-ip>:8080 bây giờ sẽ bị từ chối hoặc time out, trong khi hostname HTTPS vẫn hoạt động bình thường.

Đóng đăng ký sau khi đã tạo profile

Chế độ đăng ký được mở mặc định và guest mode cũng đang bật. Trên một hostname công khai, điều này có nghĩa là bất kỳ ai tìm thấy URL đều có thể tạo profile trên server của bạn. Hãy đăng ký profile của riêng bạn trước, sau đó tìm user ID: ls data/ liệt kê một file tên là state-<uid>.json cho mỗi người dùng, và <uid> đó chính là giá trị bạn cần.

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

Chạy lại docker compose up -d. Phần Settings giờ đây hiển thị Admin dashboard, nơi bạn tạo và thu hồi invite code, để những người bạn huấn luyện cùng có thể đăng ký và không ai khác làm được điều đó. openGym không hỗ trợ các identity provider bên ngoài, vì vậy các invite code này chỉ quản lý ứng dụng này và không ảnh hưởng đến bất kỳ thứ gì khác trên máy chủ; nếu bạn muốn cấp một tài khoản duy nhất cho mỗi người trên tất cả các dịch vụ đang chạy, sử dụng Authentik làm forward auth proxy sẽ chặn hostname trước khi màn hình đăng nhập passkey của openGym kịp tải.

Dữ liệu nằm ở đâu và bản backup bảo vệ dữ liệu

Mọi thứ nằm trong thư mục ./data, được mount vào API container tại /data. Có bốn loại file: db.json chứa profile và credential passkey public, state-<uid>.json chứa routine, workout và cân nặng của một người dùng, secret là session cookie key, còn vapid.json chứa các push notification key được tạo trong lần chạy đầu tiên.

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

Trước tiên hãy dừng API để các file vẫn nhất quán với nhau trong khi tar sao chép chúng. Ở v1.2.7, API ghi database và JSON trạng thái workout vào file tạm, sau đó đổi tên file tạm đè lên file đích theo cách atomic. Vì vậy, API không ghi đè trực tiếp các file đang hoạt động. Sau đó hãy copy archive ra khỏi server, vì archive nằm trên VPS sẽ không tồn tại nếu VPS gặp sự cố. Không đưa media/ vào backup: thư mục này chứa 140 MB ảnh bài tập và media job sẽ tự tải lại miễn phí.

Khôi phục nghĩa là untar vào đúng path trên một host phục vụ cùng domain. Passkey lưu trên điện thoại được giới hạn theo RP ID nơi nó được tạo. Vì vậy, khôi phục sang hostname mới sẽ cho bạn một database hoạt động nhưng không ai có thể đăng nhập. Hãy giữ nguyên domain hoặc chuẩn bị đăng ký lại mọi passkey. Nguyên tắc này cũng áp dụng cho mọi thứ khác bạn tự chạy, còn backup và nâng cấp một Docker Compose stack trình bày quy trình tổng quát.

Máy chủ MCP được cố định phiên bản chỉ đọc và chạy trên máy của bạn

MCP (model context protocol) là cách client như Claude Desktop hoặc Cursor giao tiếp với một tool server cục bộ. openGym cung cấp sẵn một server tại mcp/. Server này không nằm trong file compose, không phải là container và không listen trên cổng nào. Client khởi động server dưới dạng tiến trình con và giao tiếp với server qua stdio. Server được cố định phiên bản chỉ đọc các file cục bộ; server hiện tại cũng gửi dữ liệu workout lên openGym API đã ghép nối với bạn.

Hãy cài server ở nơi client chạy, không phải trên server:

cd openGym/mcp
npm install

Sau đó thêm server vào 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 là tùy chọn trong bản cài đặt một người dùng, khi server tự phát hiện profile duy nhất mà nó tìm thấy. Ở branch mặc định hiện tại, server cung cấp 11 tool: list_routines, get_routine, preview_session, get_week_plan, list_workouts, get_workout, get_bodyweight, estimate_1rm, muscle_balance, get_programme và log_workout. preview_session hiển thị chính xác nội dung app sẽ đưa lên màn hình khi bạn bắt đầu một routine, sau khi progression policy và lịch sử của bạn đã thay đổi plan. Tag v1.2.7 cung cấp 8 tool chỉ đọc, không có preview_session, get_programme hoặc log_workout. Assistant dùng server được cố định phiên bản này có thể trả lời bạn đã bench mức nào vào tuần trước, nhưng không thể log một set, sửa routine hoặc xóa dữ liệu. Ở branch hiện tại, 10 tool đọc dữ liệu và log_workout lưu workout qua server của bạn sau khi ghép nối; tool này mặc định tắt cho đến khi được ghép nối. Danh sách đó là một ví dụ ngắn gọn cho nguyên tắc mà thiết kế agent luôn quay lại: các tool bạn expose quyết định toàn bộ những gì model có thể làm, và tự viết vòng lặp để hiểu agent hoạt động thế nào là cách nhanh nhất để thấy vì sao bộ tool chỉ đọc là một lựa chọn thiết kế, không phải một hạn chế.

Đây là phần mà người dùng VPS phải xử lý. OPENGYM_DATA là một filesystem path, còn dữ liệu của bạn nằm trên VPS trong khi AI client chạy trên laptop. Có 2 lựa chọn phản ánh đúng tình huống này.

  1. Copy dữ liệu xuống và trỏ server vào bản copy: rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/, sau đó đặt OPENGYM_DATA thành ~/opengym-data. Server được cố định phiên bản chỉ đọc dữ liệu, nên copy không làm mất gì. Chạy lại rsync khi bạn muốn cập nhật số liệu.
  2. Chạy server qua SSH, đặt command thành ssh và args thành ["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]. Cách này yêu cầu Node được cài trên VPS và tài khoản đăng nhập không in gì ra stdout, vì stdout là kênh protocol.

Cả 2 lựa chọn đều giả định agent chạy trên laptop của bạn. Nếu muốn agent chạy trên cùng máy với dữ liệu, OneCLI cung cấp cho mỗi người một agent chạy trong sandbox trên server để chặng stdio quay về data/ lại là kết nối cục bộ.

Nếu cat data/db.json trả về Permission denied, API container đã ghi các file đó bằng root và tài khoản đăng nhập của bạn không thể đọc chúng. Hãy copy chúng bằng sudo hoặc đổi ownership trên host. Với các server cần listen qua network thay vì qua stdio, xem cách chạy MCP server trên VPS.

openGym hay wger: bạn nên chạy cái nào?

wger là lựa chọn đã có tên tuổi trong lĩnh vực này và là một phần mềm lớn hơn nhiều. Stack compose của nó chạy gunicorn để phục vụ ứng dụng Django, PostgreSQL, Redis và một Celery worker nằm sau nginx. Đổi lại, bạn có tính năng theo dõi dinh dưỡng và thành phần thực phẩm, một REST API có tài liệu đầy đủ, cơ sở dữ liệu bài tập cộng đồng lớn và các tính năng dành cho huấn luyện viên quản lý kế hoạch của người khác.

openGym chỉ gồm hai container, một thư mục chứa các file JSON và không có tài khoản nào cần quản trị ngoài passkey. Đó là toàn bộ sự khác biệt. Nếu bạn đã từng duy trì một bản cài đặt Chatwoot, nơi việc sao lưu đồng nghĩa với một bản dump Postgres cùng với thư mục uploads và mỗi lần nâng cấp phiên bản đều phải chạy migration cơ sở dữ liệu, thì bạn đã biết hình thái của wger đòi hỏi gì ở khâu bảo trì.

Hãy chạy wger nếu bạn muốn theo dõi thực phẩm song song với việc tập luyện, hoặc nếu bạn cần một API để phát triển ứng dụng dựa trên đó. Hãy chạy openGym nếu bạn muốn một stack đủ nhỏ để đọc hiểu từ đầu đến cuối trong một buổi chiều và một cơ chế đăng nhập không có mật khẩu để bị lộ. Cái giá của lựa chọn đó là sự trưởng thành: tính đến ngày 19 tháng 8 năm 2026, bản phát hành đầu tiên của openGym mới chỉ được một tháng tuổi, trong khi wger đã có nhiều năm phát hành phía sau. Hãy ghim phiên bản, thực hiện sao lưu và đọc ghi chú phát hành trước mỗi lần cập nhật.

Nếu bạn vẫn đang quyết định xem cái gì xứng đáng chiếm dung lượng trên máy chủ, những gì đáng để tự host trong năm 2026 sẽ đề cập đến các sự đánh đổi, và ứng dụng này hoàn toàn phù hợp khi đặt cạnh Mealie cho công thức nấu ăn hoặc Actual Budget cho quản lý tài chính trên cùng một VPS nhỏ.

Cập nhật mà không làm mất dữ liệu

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

Chuyển sang phiên bản bạn muốn bằng git checkout v<new>, sau đó chạy docker compose up -d --build để các container được build lại từ tag đó. Luôn thực hiện backup trước, vì quy trình khôi phục các file JSON trên ổ cứng chỉ cần một lệnh tar và chỉ mất vài giây.

FAQ

Tại sao openGym không bao giờ hiển thị prompt passkey trên điện thoại của tôi?

Trình duyệt từ chối tạo credential vì bạn đang dùng http:// hoặc một địa chỉ IP trực tiếp, chẳng hạn như http://192.168.1.20:8080. Trình duyệt chỉ cho phép passkey trên origin HTTPS, với localhost là ngoại lệ duy nhất. Đặt openGym phía sau reverse proxy có chứng chỉ thật cho hostname thật, đặt RP_ID=gym.example.com và ORIGIN=https://gym.example.com trong .env, rồi chạy docker compose up -d để các container nhận giá trị mới. Nếu prompt xuất hiện nhưng khi đăng nhập lại báo verification failed, hai giá trị đó không khớp chính xác với URL trong thanh địa chỉ.

openGym lưu dữ liệu của tôi ở đâu và tôi sao lưu dữ liệu đó như thế nào?

Dữ liệu nằm trong thư mục ./data cạnh file compose và được mount vào API container tại /data. Thư mục này chứa db.json cho profile và credential passkey công khai, một state-<uid>.json cho mỗi user để lưu bài tập và cân nặng, secret cho session cookie key, và vapid.json cho push notification key. Sao lưu bằng docker compose stop api, sau đó chạy tar czf ~/opengym-$(date +%F).tar.gz data/, rồi chạy docker compose start api và chép archive ra khỏi server. Bỏ qua media/. Đây là 140 MB ảnh bài tập mà media job sẽ tự tải lại.

Claude có thể đọc lịch sử tập luyện openGym của tôi không?

Có, thông qua MCP server tùy chọn trong thư mục mcp/. Server v1.2.7 được ghim phiên bản này có tám read-only tool. Nhánh mặc định hiện tại có mười một tool: mười tool để đọc routine, bản xem trước session, kế hoạch tuần, workout, cân nặng, one-rep max ước tính, cân bằng cơ và programme; log_workout ghi workout thông qua server của bạn sau khi pairing. Đây không phải container và không mở port nào. Client khởi động server qua stdio, còn các read tool của server truy cập trực tiếp vào file JSON tại OPENGYM_DATA. Vì đây là một filesystem path, nếu chạy openGym trên VPS thì bạn phải đồng bộ bản sao của data/ xuống máy chạy client, hoặc gọi server thông qua ssh trong cấu hình client.

Tôi nên tự host openGym hay wger?

Chọn wger nếu bạn muốn theo dõi thực phẩm và dinh dưỡng bên cạnh nhật ký tập luyện, hoặc muốn có REST API được tài liệu hóa để phát triển tiếp. wger chạy một stack lớn hơn: Django dưới gunicorn, PostgreSQL, Redis và một Celery worker phía sau nginx. Chọn openGym nếu bạn muốn hai container, các file JSON có thể đọc bằng cat, và đăng nhập bằng passkey mà không phải quản lý password. Tính đến ngày 19 August 2026, bản release đầu tiên được tag của openGym mới được một tháng, vì vậy hãy checkout một git tag và sao lưu data/ trước mỗi lần update.

Bài viết này có hữu ích không?