SparkyFitness: theo dõi ăn uống, tập luyện, sức khoẻ tự host — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về CodeWithCJ/SparkyFitness — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: SparkyFitness: theo dõi sức khoẻ cả nhà, tự cài — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
SparkyFitness là nền tảng theo dõi dinh dưỡng, tập luyện và sức khoẻ mà bạn tự chạy trên máy chủ của mình, dữ liệu không phải gửi cho bên thứ ba. Repo có server, web, app iOS/Android và app cho đồng hồ. Cách cài chính thức là Docker Compose, khoảng 5 bước, người mới làm theo được nếu biết mở terminal.
SparkyFitness là một nền tảng theo dõi sức khoẻ "tự host": bạn chạy nó trên máy chủ hoặc máy tính của mình, rồi ghi lại ăn uống, tập luyện, nước uống, giấc ngủ, cân nặng… ở một nơi duy nhất. Tác giả định vị nó là phương án thay thế cho các app như MyFitnessPal, Flo hay Hevy, nhưng dữ liệu nằm trong hạ tầng của bạn.
Nếu bạn từng thấy mình trả tiền cho một app đếm calo, một app ghi buổi tập, một app theo dõi giấc ngủ rồi vẫn không có báo cáo gộp, repo này nhắm đúng chỗ đó. Nó hợp với người muốn giữ dữ liệu sức khoẻ cho riêng mình, với gia đình muốn theo dõi chung, và với dev mới thích tự dựng một dịch vụ bằng Docker.
Điểm đáng giá nhất: một server duy nhất phục vụ cả web, app di động và app đồng hồ, kèm nhiều kết nối với dịch vụ sức khoẻ như Apple Health, Google Health Connect, Garmin Connect, Fitbit. Hiện repo có khoảng 6.777 sao và 468 fork, và vẫn được cập nhật trong 3 tháng gần đây.
CodeWithCJ/SparkyFitness
Nền tảng tự host theo dõi ăn uống, tập luyện, nước uống, giấc ngủ và chỉ số cơ thể cho cả gia đình, có app di động và trợ lý AI (beta).
I.SparkyFitness làm được gì
Dưới đây là các nhóm tính năng chính, mình diễn giải theo lợi ích thực tế.
A.Theo dõi nhiều thứ trong một chỗ
App ghi dinh dưỡng, tập luyện, uống nước, giấc ngủ, nhịn ăn (fasting), tâm trạng và số đo cơ thể. Bạn không phải mở nhiều app khác nhau. Có thêm phần đặt mục tiêu và check-in hằng ngày để giữ nhịp.
B.Biểu đồ và báo cáo dài hạn
Có biểu đồ tương tác và báo cáo theo thời gian. README còn ghi lịch sử đầy đủ và báo cáo theo khoảng ngày tuỳ chọn là miễn phí. Hợp với việc nhìn xu hướng cân nặng hay lượng ăn qua nhiều tháng.
C.Dùng chung cho cả gia đình
Có nhiều hồ sơ người dùng và quyền truy cập cho gia đình. Bảng so sánh trong README nói có 7 quyền chi tiết. Ví dụ bạn có thể xem số liệu của người thân mà không cần dùng chung một tài khoản. Lưu ý: tác giả xếp tính năng "Family & Friends" vào nhóm còn beta.
D.Đồng bộ từ đồng hồ và dịch vụ sức khoẻ
README liệt kê nhiều nguồn: Apple Health (iOS), Google Health Connect (Android), Fitbit, Garmin Connect, Withings, Polar Flow, Oura, Hevy, COROS, Intervals.ICU, Strava (mới thử nghiệm một phần) và nhiều dịch vụ khác. Dữ liệu như số bước, buổi tập, giấc ngủ, cân nặng được đưa về server của bạn. Có cả app đồng hành cho Apple Watch và Wear OS.
E.Tra cứu thực phẩm từ nhiều nguồn
Ngoài các cơ sở dữ liệu thực phẩm như OpenFoodFacts, USDA, Fatsecret, Nutritionix, README còn nhắc các nguồn của Thuỵ Sĩ, Canada và Thuỵ Điển. Với người Việt, bạn nên tự thử xem món ăn quen thuộc có sẵn không, vì README không nói về dữ liệu món Việt.
F.Bảo mật đăng nhập
Hỗ trợ OIDC, TOTP, Passkey, MFA. Nghĩa là bạn có thể bật xác thực hai lớp cho server của mình.
G.SparkyAI (beta)
Đây là giao diện trò chuyện để ghi dữ liệu và xem tiến độ. Bạn có thể ghi món ăn, bài tập, chỉ số cơ thể, số bước bằng cách chat, hoặc gửi ảnh món ăn để app ghi bữa ăn tự động. Nó nhớ lịch sử hội thoại để hỏi tiếp. README ghi rõ phần AI vẫn đang beta. Bảng so sánh cũng nhắc tới MCP server và việc dùng mô hình AI của riêng bạn, nhưng README không hướng dẫn chi tiết phần này.
SparkyFitness là "source-available", không phải mã nguồn mở. README nói giấy phép là phi thương mại và cần xin phép nếu dùng cho mục đích thương mại. Dùng cá nhân hoặc trong gia đình thì không vướng, còn nếu định dùng cho kinh doanh, bạn hãy đọc file LICENSE trong repo trước.
II.Cần chuẩn bị gì
Theo README, cách cài "tự host" dùng Docker Compose. Vì vậy bạn cần:
- Một máy (máy tính hoặc máy chủ) đã cài Docker, có lệnh
docker compose. README không nêu phiên bản tối thiểu và cũng không nói yêu cầu phần cứng. - Một cửa sổ terminal để gõ lệnh.
- Công cụ
curlđể tải file cấu hình. Lệnh trong README dùngcurl. - Công cụ
opensslnếu bạn tự tạo khoá bằng lệnh. Nếu không có, dùng trình tạo.envtrên web (xem ở dưới) cho dễ. - Một mật khẩu mạnh cho cơ sở dữ liệu và vài khoá bí mật (sẽ nói ở bước 3).
Các lệnh trong README viết kiểu shell (bash). Nếu bạn dùng Windows, README chưa nói rõ cách làm riêng, nên cách ổn nhất là chạy trong một terminal có sẵn các lệnh đó, hoặc làm theo trang tài liệu chính thức của dự án.
README không yêu cầu tài khoản hay API key để chạy server. Riêng tính năng AI hoặc kết nối từng dịch vụ (Fitbit, Garmin…) có thể cần thêm cấu hình, nhưng README không ghi chi tiết ở đây. Chỗ để xem là trang tài liệu: https://codewithcj.github.io/SparkyFitness/
III.Cài đặt từng bước
- Tạo thư mụcTạo một thư mục riêng tên sparkyfitness và đi vào đó
- Tải docker-compose.ymlLấy file khai báo chạy sẵn từ repo
- Tạo file .envTải mẫu cấu hình hoặc tạo bằng trình tạo trên web
- Điền khoá bí mậtThay các giá trị mẫu bằng mật khẩu và khoá thật
- Khởi độngKéo image về và chạy bằng docker compose, rồi mở cổng 3004
A.Bước 1: Tạo thư mục làm việc
Mở terminal rồi chạy hai lệnh sau. Lệnh đầu tạo thư mục, lệnh sau đi vào thư mục đó. Mọi file cấu hình sẽ nằm ở đây, nên bạn nhớ chạy các lệnh tiếp theo trong cùng thư mục.
mkdir sparkyfitness && cd sparkyfitnessNếu terminal của bạn không hiểu && (một số bản PowerShell cũ), hãy chạy mkdir sparkyfitness rồi cd sparkyfitness thành hai lệnh riêng.
B.Bước 2: Tải file docker-compose.yml
Lệnh này tải file khai báo cách chạy bản production từ repo và lưu thành docker-compose.yml trong thư mục hiện tại.
curl -L -o docker-compose.yml https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/docker-compose.prod.ymlTrên Windows PowerShell, curl đôi khi là bí danh của một lệnh khác và không hiểu cờ -L. Nếu gặp lỗi, thử gõ curl.exe thay cho curl.
C.Bước 3: Tạo file .env
File .env chứa cấu hình và mật khẩu của bạn. README đưa ba lựa chọn.
Lựa chọn A (README khuyên dùng): tạo .env ngay trên trình duyệt, trang này tự sinh khoá bảo mật cho bạn:
# Option A (Recommended): Generate custom .env with 1-click secure keys in browser:
# https://codewithcj.github.io/SparkyFitness/install/env-generatorVới người mới, mình khuyên chọn cách này vì bạn không phải tự gõ openssl. Sau khi tạo, lưu nội dung thành file tên .env (có dấu chấm ở đầu) trong thư mục sparkyfitness.
Lựa chọn B: bản mẫu tối giản, chỉ 5 giá trị, còn lại dùng mặc định. README nói là đủ cho đa số bản tự host:
curl -L -o .env https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/.env.simple.exampleLựa chọn C: bản đầy đủ mọi biến, dành cho khi bạn cần đăng nhập SSO, gửi email SMTP, dùng database ngoài hoặc reverse proxy. Trong README lệnh này đang để dạng chú thích (có dấu #), bạn bỏ dấu # nếu muốn dùng:
curl -L -o .env https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/.env.exampleD.Bước 4: Thay các giá trị mẫu
Nếu bạn dùng lựa chọn A thì bỏ qua bước này, vì trình tạo đã điền sẵn. Nếu dùng B hoặc C, mở file .env bằng trình soạn thảo và thay các giá trị sau:
# SPARKY_FITNESS_DB_PASSWORD any strong password
# SPARKY_FITNESS_API_ENCRYPTION_KEY openssl rand -hex 32 (64 hex chars)
# BETTER_AUTH_SECRET openssl rand -base64 32 (44 chars)
# SPARKY_FITNESS_FRONTEND_URL the URL you will open the app atÝ nghĩa từng dòng:
SPARKY_FITNESS_DB_PASSWORD: mật khẩu cơ sở dữ liệu, đặt một mật khẩu mạnh bất kỳ.SPARKY_FITNESS_API_ENCRYPTION_KEY: khoá mã hoá, tạo bằngopenssl rand -hex 32(ra 64 ký tự hex).BETTER_AUTH_SECRET: khoá cho phần đăng nhập, tạo bằngopenssl rand -base64 32(ra 44 ký tự).SPARKY_FITNESS_FRONTEND_URL: địa chỉ bạn sẽ gõ vào trình duyệt để mở app, ví dụ nếu chạy trên máy mình thì là địa chỉ ở bước 5.
Chỗ dễ vấp: README nói server sẽ không chịu khởi động nếu bạn để nguyên các giá trị mẫu, vì nếu không thì database sẽ được tạo với một mật khẩu đã công khai. Đây là cơ chế bảo vệ, không phải lỗi.
Đừng đăng file .env lên GitHub, nhóm chat hay ảnh chụp màn hình. Trong đó có mật khẩu database và khoá mã hoá dữ liệu sức khoẻ của bạn. Hãy lưu một bản sao ở nơi an toàn, vì mất khoá thì bạn có thể không đọc lại được dữ liệu cũ.
E.Bước 5: Khởi động ứng dụng
Vẫn trong thư mục sparkyfitness, chạy:
docker compose pull && docker compose up -ddocker compose pull tải các image về máy, docker compose up -d chạy các container ở chế độ nền. Lần đầu có thể mất vài phút vì phải tải. Xong rồi mở trình duyệt, vào:
# Access application at http://localhost:3004Nếu bạn cài trên máy chủ khác, thay localhost bằng địa chỉ máy đó, và nhớ để SPARKY_FITNESS_FRONTEND_URL khớp với địa chỉ này.
Muốn cấu hình sâu hơn (reverse proxy, các cách cài khác), README chỉ sang trang tài liệu: https://codewithcj.github.io/SparkyFitness/
IV.Kiểm tra đã chạy được chưa
Dấu hiệu thành công theo README: bạn mở được http://localhost:3004 và thấy giao diện web của SparkyFitness. Từ đó bạn tạo tài khoản và đăng nhập.
Nếu trang không mở, bạn có thể xem trạng thái các container bằng lệnh Docker phổ thông:
docker compose ps
docker compose logsLệnh đầu cho biết container nào đang chạy hoặc đã thoát. Lệnh sau in ra nhật ký, nơi thường có thông báo lỗi rõ ràng (ví dụ chưa thay giá trị mẫu trong .env). README không mô tả chi tiết nội dung nhật ký, nên bạn cứ đọc thông báo trong đó.
V.Dùng vào việc thật
README không đưa ví dụ từng bước cho các tình huống dưới đây. Mình dựa trên danh sách tính năng trong README để gợi ý cách dùng. Chi tiết thao tác trên giao diện bạn sẽ thấy khi vào app.
A.Gia đình muốn theo dõi sức khoẻ chung
Bối cảnh: vợ chồng và bố mẹ cùng muốn đếm calo, uống nước, theo dõi cân nặng, nhưng không muốn mỗi người một app và một khoản phí.
Cách làm: dựng một server SparkyFitness ở nhà (hoặc trên một máy chủ nhỏ), tạo hồ sơ cho từng người. Dùng tính năng chia sẻ cho gia đình để người này xem được số liệu của người kia theo quyền bạn cho phép.
Kết quả: một nơi duy nhất cho cả nhà, dữ liệu nằm trong máy của mình. Nhớ rằng tính năng "Family & Friends" còn ở mức beta nên có thể gặp lỗi vặt.
Dữ liệu sức khoẻ của cả nhà nằm trong máy của mình, không nằm trong tài khoản của ai khác.
Ông T
B.Người tập gym, chạy bộ muốn gom số liệu từ đồng hồ
Bối cảnh: bạn dùng đồng hồ Garmin hoặc Fitbit, ghi buổi tập ở một app, ăn uống ở app khác, và không có báo cáo chung.
Cách làm: cài app di động của SparkyFitness (README trỏ tới wiki cho iOS và Android), bật đồng bộ với Apple Health hoặc Google Health Connect, hoặc kết nối trực tiếp dịch vụ như Garmin Connect, Fitbit. Số bước, buổi tập, giấc ngủ và cân nặng sẽ được đưa về server.
Kết quả: xem biểu đồ dài hạn và báo cáo theo khoảng ngày bạn chọn ngay trong một app. Mỗi dịch vụ có cách kết nối riêng, bạn xem hướng dẫn tại tài liệu của dự án.
C.Nhân viên văn phòng ghi bữa ăn bằng chat
Bối cảnh: bạn bận, không muốn mở danh sách thực phẩm để chọn từng món.
Cách làm: bật phần SparkyAI (beta), rồi chat để ghi món ăn, hoặc gửi ảnh bữa ăn để app tự ghi. Ví dụ bạn có thể nhắn một câu mô tả bữa trưa, hoặc chụp ảnh đĩa cơm.
Kết quả: bữa ăn được ghi lại và bạn có thể hỏi tiếp về tiến độ vì app nhớ lịch sử trò chuyện. Vì README chưa ghi cách cấu hình mô hình AI, bạn hãy xem trang tài liệu để biết cần thiết lập gì. Và vì đang beta, bạn nên kiểm tra lại số liệu mà AI ghi.
D.Dev mới muốn tự host và thử đồ chơi mới
Bối cảnh: bạn đang học Docker và muốn một dự án thật để thực hành.
Cách làm: làm theo các bước ở trên, sau đó thử cấu hình nâng cao như reverse proxy hoặc SSO bằng file .env đầy đủ (lựa chọn C). Repo còn có thư mục helm/, umbrel/ và nix/ cho các cách triển khai khác, nhưng README chưa hướng dẫn chi tiết, bạn xem trong tài liệu.
Kết quả: bạn có một dịch vụ chạy thật, đủ để học cách quản lý container, sao lưu và nâng cấp. Repo có sẵn db_backup.sh và DB Backup.cmd ở thư mục gốc, nhưng README không nói cách dùng, nên hãy đọc nội dung file trước khi chạy.
VI.Lỗi hay gặp và cách xử lý
A.Server không khởi động sau khi chạy docker compose
Nguyên nhân thường gặp nhất: bạn chưa thay các giá trị mẫu trong .env. README nói rõ server từ chối chạy khi còn để nguyên placeholder. Cách xử lý: mở .env, điền mật khẩu và khoá thật như ở bước 4, rồi chạy lại docker compose up -d. Dùng trình tạo .env trên web sẽ tránh được lỗi này.
B.Lệnh curl hoặc openssl báo không tìm thấy
Trên Windows, máy có thể chưa có openssl, hoặc curl bị hiểu thành lệnh khác. Cách xử lý an toàn: dùng trình tạo .env trên trình duyệt thay cho openssl, và thử curl.exe thay cho curl.
C.Không mở được trang localhost:3004
Kiểm tra Docker đã chạy chưa, rồi dùng docker compose ps xem container có đang chạy không. Nếu một container thoát, xem docker compose logs để biết lý do. Nếu bạn cài ở máy khác, nhớ gõ đúng địa chỉ máy đó và để SPARKY_FITNESS_FRONTEND_URL khớp với địa chỉ bạn dùng. README không liệt kê thêm lỗi cổng hay tường lửa, nên đây là chỗ bạn cần tự kiểm tra thêm.
D.Hỏng dữ liệu hoặc lỗi sau khi nâng cấp
README cảnh báo dự án đang phát triển nhanh và có thể có thay đổi gây lỗi giữa các bản. Họ không khuyến khích tự động cập nhật container, và khuyên luôn đọc ghi chú phát hành trước khi nâng cấp. Cách xử lý: sao lưu cơ sở dữ liệu trước, đọc CHANGELOG.md hoặc ghi chú phát hành, rồi mới chạy docker compose pull và docker compose up -d.
E.Tính năng beta chạy không như mong đợi
Chatbot AI, truy cập gia đình/bạn bè và tài liệu API đều được ghi là beta. Nếu gặp lỗi, bạn có thể đăng vào mục Issues/Discussions trên GitHub, hoặc hỏi ở cộng đồng Discord mà README có dẫn link.
VII.Có nên dùng không
Điểm mạnh. Bạn giữ toàn quyền với dữ liệu sức khoẻ, không phụ thuộc dịch vụ bên thứ ba. Một app gom nhiều mảng: ăn uống, tập luyện, giấc ngủ, nhịn ăn, số đo cơ thể. Có app di động, app đồng hồ và nhiều kết nối với dịch vụ sức khoẻ. Cài đặt chính thức là Docker Compose chỉ vài lệnh. Dự án vẫn được cập nhật đều.
Giới hạn. Một số điểm bạn nên biết trước:
- Bạn phải tự vận hành: tự giữ
.env, tự sao lưu, tự nâng cấp. Không có ai làm hộ. - Dự án đang phát triển nhanh, có thể có thay đổi gây lỗi giữa các bản, và README không khuyên tự động cập nhật.
- Một số tính năng còn beta: chatbot AI, truy cập gia đình/bạn bè, tài liệu API.
- Giấy phép là source-available, phi thương mại. Dùng cho kinh doanh cần xin phép.
- README chưa nói gì về dữ liệu món ăn Việt Nam hay giao diện tiếng Việt cho ứng dụng. Bạn nên tự dùng thử. README có liệt kê tiếng Việt trong danh sách ngôn ngữ của tài liệu, nhưng đó chưa chắc là ngôn ngữ giao diện app.
- Bảng so sánh trong README do chính dự án viết, nên hãy đọc với con mắt tỉnh táo. Chính tác giả cũng nói có chỗ đã lỗi thời.
Khi nào nên chọn cách khác. Nếu bạn không muốn đụng vào Docker hay server, một app thương mại có sẵn sẽ đỡ công hơn. README có nhắc tới các nhà cung cấp cloud bên thứ ba để chạy hộ, nhưng đó là dịch vụ độc lập và bạn cần tự tìm hiểu kỹ. Nếu bạn cần dùng cho mục đích kinh doanh thì hãy kiểm tra giấy phép trước. Còn nếu bạn muốn giữ dữ liệu của gia đình mình và không ngại làm vài lệnh, SparkyFitness là một lựa chọn đáng thử.
Câu hỏi thường gặp
SparkyFitness có miễn phí không?
README nói bạn dùng được mà không cần thuê bao hay quảng cáo, và lịch sử đầy đủ cùng báo cáo theo khoảng ngày cũng miễn phí. Tuy nhiên giấy phép là source-available, phi thương mại và cần xin phép nếu dùng cho kinh doanh. Chi phí máy chủ để chạy thì README chưa nói.
Có phải mã nguồn mở không?
Không. README ghi rõ SparkyFitness là source-available, không phải open source, vì giấy phép phi thương mại và cần xin phép cho mục đích thương mại. Bạn nên đọc file LICENSE trong repo trước khi dùng cho công việc kinh doanh.
Cài trên Windows được không, có cần GPU không?
README hướng dẫn cài bằng Docker Compose bằng các lệnh kiểu shell và không nêu yêu cầu GPU. README cũng không nói riêng về Windows, nên bạn xem trang tài liệu của dự án để chắc chắn. Thông tin về cấu hình phần cứng tối thiểu hiện chưa có trong README.
Dữ liệu của tôi có an toàn không?
README nhấn mạnh dữ liệu được lưu trên hạ tầng bạn kiểm soát, không phụ thuộc dịch vụ bên thứ ba. Ứng dụng hỗ trợ OIDC, TOTP, Passkey, MFA. An toàn thực tế còn phụ thuộc cách bạn bảo vệ server và file .env của mình.
Khác gì MyFitnessPal hay các app đếm calo khác?
Theo README, điểm khác là tự host nên dữ liệu ở máy bạn, không thuê bao, gộp nhiều mảng sức khoẻ vào một app và có chia sẻ cho cả gia đình. Bảng so sánh đó do chính dự án viết, nên bạn đọc với con mắt tỉnh táo.
Tôi không rành kỹ thuật thì sao?
README có hướng thứ hai dành cho người không rành kỹ thuật: chạy một bản trên đám mây của nhà cung cấp bên thứ ba. README nói đây là các dịch vụ độc lập và bạn tự cân nhắc. Danh sách nhà cung cấp cụ thể và giá cả chưa có trong tư liệu mình có.
Phần AI (SparkyAI) có dùng ngay được không?
README ghi tính năng AI đang ở mức beta, có thể còn lỗi. Bạn có thể chat để ghi món ăn, bài tập, chỉ số cơ thể, số bước hoặc gửi ảnh món ăn. Cách cấu hình mô hình AI hay chi phí gọi AI chưa có trong README, bạn xem trang tài liệu.


