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 ships a Docker-based development environment that brings up the frontend, backend, and PostgreSQL database with a single command and live-reloading on every file change. If you prefer to run services directly on your machine, a local pnpm workflow is also supported. Either way, the steps below get you from a fresh clone to a running application in minutes.

​
Prerequisites

Docker (recommended)

  • Docker & Docker Compose — required to run the containerised stack
  • Git — for cloning the repository
No Node.js, pnpm, or PostgreSQL installation needed when using Docker.

Local dev (without Docker)

  • Node.js 18+ and pnpm
  • PostgreSQL 15+
  • Git
Required when you want to run services directly on your machine.
1

Clone the repository

git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness
2

Copy the environment template

cp docker/.env.example .env
3

Generate an encryption key

The SPARKY_FITNESS_API_ENCRYPTION_KEY variable must be a 64-character hex string. Generate and inject one automatically:
sed "s/SPARKY_FITNESS_API_ENCRYPTION_KEY=changeme_replace_with_a_64_character_hex_string/SPARKY_FITNESS_API_ENCRYPTION_KEY=$(openssl rand -hex 32)/" \
  .env > .env.tmp && mv .env.tmp .env
Alternatively, generate the key manually and paste it into .env:
openssl rand -hex 32
# or
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
4

(Optional) Update the frontend URL

If Docker is running on a remote machine, update SPARKY_FITNESS_FRONTEND_URL in .env to match that machine’s IP or hostname.
5

Start the development stack

./docker/docker-helper.sh dev up
The first run pulls or builds images; subsequent starts are much faster.
The docker-helper.sh script is the recommended way to manage every lifecycle operation — starting, stopping, viewing logs, rebuilding, and cleaning. Run ./docker/docker-helper.sh help at any time to see all available commands.

​
Service URLs

ServiceURLNotes
Frontendhttp://localhost:8080Live-reload enabled in dev mode
Backend APIhttp://localhost:3010Direct access; dev mode only
PostgreSQLlocalhost:5432Direct access for debugging
Production (nginx)http://localhost:3004Single entry point in prod mode

​
Docker Helper Script

The ./docker/docker-helper.sh script wraps Docker Compose with validation and convenience commands: 
# Start development environment (live reloading)
./docker/docker-helper.sh dev up

# Start production environment (optimised builds)
./docker/docker-helper.sh prod up

# Stop all services
./docker/docker-helper.sh down

# View logs for all services
./docker/docker-helper.sh logs

# View logs for a specific service
./docker/docker-helper.sh logs backend

# Rebuild all images
./docker/docker-helper.sh build

# Restart all services (or a specific one)
./docker/docker-helper.sh restart
./docker/docker-helper.sh restart frontend

# Remove all containers, networks, and volumes
./docker/docker-helper.sh clean

# Show all available commands
./docker/docker-helper.sh help

​
Development vs production environments

Featuredev upprod up
Live reloading✅ Frontend + backend❌
Local code volumes✅ Mounted❌ Uses built images
Direct DB access✅ Port 5432 exposed❌ Internal only
Backend API exposed✅ Port 3010❌ Proxied via nginx
Image sourceBuilt locallyPulled from DockerHub

​
Local Development (Without Docker)

If you prefer to run services directly on your machine, follow these steps:
1

Install pnpm and clone the repo

npm install -g pnpm
git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness
2

Install all workspace dependencies

pnpm install
This installs dependencies for all packages defined in pnpm-workspace.yaml (frontend, backend, mobile, shared, docs).
3

Create and configure the database

CREATE DATABASE sparkyfitness;
CREATE USER sparky WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE sparkyfitness TO sparky;
4

Configure environment variables for the backend

cd SparkyFitnessServer
cp .env.example .env
# Edit .env with your database credentials and secrets
Key variables:
SPARKY_FITNESS_DB_HOST=localhost
SPARKY_FITNESS_DB_PORT=5432
SPARKY_FITNESS_DB_NAME=sparkyfitness_db
SPARKY_FITNESS_DB_USER=sparky
SPARKY_FITNESS_DB_PASSWORD=your_password
SPARKY_FITNESS_APP_DB_USER=sparky_app
SPARKY_FITNESS_APP_DB_PASSWORD=your_app_password
PORT=3010
NODE_ENV=development
BETTER_AUTH_SECRET=your_better_auth_secret
SPARKY_FITNESS_API_ENCRYPTION_KEY=<64-char hex string>
5

Run database migrations and start the backend

# From SparkyFitnessServer/
pnpm run migrate
pnpm run dev
6

Start the frontend

# From SparkyFitnessFrontend/
pnpm dev
The frontend dev server proxies /api, /health-data, and /uploads to the backend on port 3010.

​
Environment Variables Reference

Copy the template and edit as needed: 
cp docker/.env.example .env

SPARKY_FITNESS_DB_HOST=localhost
SPARKY_FITNESS_DB_PORT=5432
SPARKY_FITNESS_DB_NAME=sparkyfitness_db
SPARKY_FITNESS_DB_USER=sparky
SPARKY_FITNESS_DB_PASSWORD=your_password

# App DB user (limited privileges, used at runtime)
SPARKY_FITNESS_APP_DB_USER=sparky_app
SPARKY_FITNESS_APP_DB_PASSWORD=your_app_password

PORT=3010
NODE_ENV=development
BETTER_AUTH_SECRET=your_better_auth_secret_here
SPARKY_FITNESS_API_ENCRYPTION_KEY=<64-char hex string>

# Set this to your machine's address when running Docker remotely
SPARKY_FITNESS_FRONTEND_URL=http://localhost:8080

OPENAI_API_KEY=sk-...
GOOGLE_AI_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...
AI features are optional — the app runs fully without them.

​
Running Tests

SparkyFitness uses Jest / Vitest for JavaScript and TypeScript testing across the frontend, backend, and mobile packages, and pytest for the Garmin microservice. 
# Frontend (Vite + React) — from SparkyFitnessFrontend/
pnpm test          # Watch mode
pnpm test:ci       # Single run with coverage

# Backend (Node.js + Express) — from SparkyFitnessServer/
pnpm test          # Watch mode
pnpm test:ci       # Single run with coverage

# Mobile (React Native + Expo) — from SparkyFitnessMobile/
npm run test:run   # Single run
npm run test:ci    # Single run with coverage

# Garmin microservice (Python) — from SparkyFitnessGarmin/
pytest --cov=. --cov-report=html
CI runs on pull requests and pushes to main using path-based change detection — only the affected component’s tests execute. Coverage reports are uploaded as build artifacts and retained for seven days.

​
Full validation before submitting a PR

# Frontend
cd SparkyFitnessFrontend && pnpm run validate

# Backend
cd SparkyFitnessServer && pnpm run typecheck && pnpm run lint && pnpm run test

# Mobile
cd SparkyFitnessMobile && pnpm run lint && pnpm run test:run -- --watchman=false --runInBand

​
Common Issues

Check which process is using a required port:
lsof -i :8080   # Frontend
lsof -i :3010   # Backend
lsof -i :5432   # Database
Stop the conflicting process or adjust the port in .env.
Ensure your user is in the docker group:
sudo usermod -aG docker $USER
# Log out and back in for the change to take effect
Verify that PostgreSQL is running and that the credentials in .env exactly match what was used when creating the database user. For the Docker stack, ensure the db service started successfully:
./docker/docker-helper.sh logs db

Build docs developers (and LLMs) love

Get started for freeTalk to us