Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodeWithCJ/SparkyFitness/llms.txt

Use this file to discover all available pages before exploring further.

SparkyFitness is an open-source, self-hosted alternative to MyFitnessPal. Track food, workouts, hydration, sleep, body measurements, and more — with full control over your data. It’s built for families, supports 20+ health device integrations, and includes an AI-powered assistant for hands-free logging.

Quick Start

Deploy SparkyFitness with Docker Compose in under five minutes.

Installation Options

Docker Compose, Kubernetes, Portainer, or build from source.

Core Features

Nutrition, exercise, body metrics, sleep, fasting, mood tracking, and more.

AI Assistant

Log food, workouts, and vitals via natural language and photo recognition.

​
What is SparkyFitness?

SparkyFitness is a full-stack fitness tracking application built with React 18 + TypeScript on the frontend and Node.js + Express + PostgreSQL on the backend. It is designed to be self-hosted on your own infrastructure — giving your family complete ownership of all health data without depending on any third-party service.

Nutrition Tracking

Log meals, create custom foods and recipes, browse integrated food databases, and analyze macros and micronutrients.

Exercise Logging

Record workouts with sets, reps, weight, and duration. Use presets, workout plans, and integrated exercise databases.

Body Metrics

Track weight, body measurements, and progress photos. Visualize trends with interactive charts.

Device Integrations

Sync with Garmin, Fitbit, Apple Health, Google Health, Withings, Polar, Strava, and more.

Family Sharing

Grant family members, trainers, or coaches granular access to your data with fine-grained permission controls.

MCP Server

Connect AI clients like Claude Desktop directly to your health data via the Model Context Protocol.

​
Get Started in 3 Steps

1

Deploy with Docker Compose

Pull the latest images and start all services with a single command:
mkdir sparkyfitness && cd sparkyfitness
curl -L -o docker-compose.yml https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/docker-compose.prod.yml
curl -L -o .env https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/default.env.example
docker compose pull && docker compose up -d
2

Configure your environment

Edit the .env file to set your database credentials, encryption key, and frontend URL. At minimum, set SPARKY_FITNESS_API_ENCRYPTION_KEY (a 64-char hex string) and BETTER_AUTH_SECRET. See the Environment Variables guide for all options.
3

Create your account

Open http://localhost:3004 in your browser, register your first account, and complete the onboarding wizard to set your goals and preferences.
For a full walkthrough including reverse proxy setup, OIDC authentication, and multi-user configuration, see the Installation Guide.

​
Key Capabilities

Privacy-First Architecture

All data stays on your infrastructure. PostgreSQL Row-Level Security ensures strict per-user data isolation, even in multi-user deployments.

AI-Powered Logging

SparkyAI lets you log meals, workouts, and vitals by chatting or uploading a photo — powered by OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint.

20+ Integrations

Automatic sync from wearables and health platforms: Garmin, Fitbit, Withings, Apple Health, Google Health, Polar, Strava, Hevy, and more.

Developer API

REST API with JWT and API key authentication. Ingest health data from iOS Shortcuts, Android automations, or any HTTP client.

​
Community & Support

Discord Community

Get help, share tips, and connect with other SparkyFitness users and contributors.

GitHub Discussions

Ask questions, report bugs, and request features on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us