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.

This guide walks you through the fastest path to a working SparkyFitness deployment. You will download the official Docker Compose file and environment template, set the required secrets, start the application, and create your first account — all in a single terminal session. No source code checkout is required.

​
Prerequisites

Before you begin, make sure the following tools are installed on your server or local machine: Verify both are available: 
docker --version
docker compose version

​
Deployment Steps

1

Download the Docker Compose file and environment template

Create a dedicated directory for SparkyFitness, then download the pre-built production Compose file and the default environment variable template directly from the latest GitHub release:
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
The Compose file defines three services — sparkyfitness-db (PostgreSQL), sparkyfitness-server (Node.js API), and sparkyfitness-frontend (React app served by Nginx) — all on an isolated Docker network.
2

Generate and set the required secrets

Open the .env file in your editor. Two secrets are required and must be set before the application will start:SPARKY_FITNESS_API_ENCRYPTION_KEY — used to encrypt stored API keys at rest. Generate a secure value with:
openssl rand -hex 32
BETTER_AUTH_SECRET — used by the authentication framework to sign and verify session tokens. Generate a separate value:
openssl rand -hex 32
Copy each output into your .env file:
SPARKY_FITNESS_API_ENCRYPTION_KEY=<paste output here>
BETTER_AUTH_SECRET=<paste output here>
You should also review and configure the database credentials in .env:
SPARKY_FITNESS_DB_NAME=sparkyfitness
SPARKY_FITNESS_DB_USER=sparky
SPARKY_FITNESS_DB_PASSWORD=<a strong password>
SPARKY_FITNESS_APP_DB_PASSWORD=<a strong password>
Never commit your .env file to version control. Both SPARKY_FITNESS_API_ENCRYPTION_KEY and BETTER_AUTH_SECRET are cryptographic secrets — losing them will break decryption of stored data and invalidate all active sessions.
3

Start the application

Pull the latest images and start all services in detached mode:
docker compose pull && docker compose up -d
Docker Compose will start the services in dependency order: the database first, then the API server, then the frontend. The API server automatically runs database migrations on startup.Check that all three containers are running:
docker compose ps
You should see sparkyfitness-db, sparkyfitness-server, and sparkyfitness-frontend all in a running state.To follow the startup logs:
docker compose logs -f
4

Access the application

Once all containers are healthy, open your browser and navigate to:
http://localhost:3004
The frontend is served by Nginx inside the sparkyfitness-frontend container, which maps container port 80 to host port 3004.
If you are accessing SparkyFitness from a different machine on your network (not localhost), update SPARKY_FITNESS_FRONTEND_URL in your .env file to your server’s IP address or hostname before starting the stack — for example http://192.168.1.100:3004. This value is used by the backend for CORS and redirect configuration. After changing it, run docker compose up -d again to apply.
5

Create your account and complete onboarding

On first visit you will be prompted to create an account. Fill in your name, email address, and a strong password, then follow the onboarding flow to:
  • Set your fitness goals (weight, calorie targets, macros)
  • Configure your measurement units (metric or imperial)
  • Optionally connect device integrations (Garmin, Fitbit, Apple Health, etc.)
After onboarding you will land on the main dashboard, ready to log your first meal or workout.
The first account registered on a fresh instance is a standard user account. To designate an admin user who can access the admin panel, set SPARKY_FITNESS_ADMIN_EMAIL in your .env to that account’s email address and restart the stack.

​
What’s Next?

Now that SparkyFitness is running, explore the rest of the documentation to get the most out of your deployment:

Environment Variables

Full reference for every .env option — database settings, email configuration, feature flags, and more.

Reverse Proxy Setup

Put SparkyFitness behind Nginx or Caddy with HTTPS so it’s safely accessible over the internet.

Authentication

Configure OIDC, TOTP two-factor authentication, Passkeys, and MFA for your users.

Device Integrations

Connect Garmin, Fitbit, Apple Health, Google Health, Withings, Strava, and more to sync data automatically.

AI Assistant

Set up SparkyAI with OpenAI, Anthropic, or Google Gemini to enable conversational food and activity logging.

Family Sharing

Add family members to your instance and configure granular data-access permissions.

Build docs developers (and LLMs) love

Get started for freeTalk to us