Docker Compose is the recommended deployment method for SparkyFitness. It orchestrates the database, backend server, and frontend into a single stack with a single command, making it the easiest way to get a self-hosted instance up and running in minutes. Both a production mode (using pre-built DockerHub images) and a development mode (with live source reloading) are supported.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.
Prerequisites
- Docker Engine 20.10+ — Download Docker Desktop (includes Engine and Compose)
- Docker Compose v2+ — bundled with Docker Desktop; verify with
docker compose version
Production Deployment
Create a directory and download the Compose files
Create a dedicated directory for SparkyFitness and download the latest production Compose file and example environment file.
Configure environment variables
Open the downloaded
For a full description of every variable, see the Environment Variables reference.
.env file in a text editor and fill in the mandatory variables. At a minimum you must set the following before the application will start:| Variable | Description |
|---|---|
SPARKY_FITNESS_DB_NAME | PostgreSQL database name (e.g. sparkyfitness_db) |
SPARKY_FITNESS_DB_USER | Superuser for migrations (e.g. sparky) |
SPARKY_FITNESS_DB_PASSWORD | Strong password for the superuser |
SPARKY_FITNESS_APP_DB_USER | Limited-privilege app user (e.g. sparkyapp) |
SPARKY_FITNESS_APP_DB_PASSWORD | Password for the app user |
SPARKY_FITNESS_FRONTEND_URL | Public URL of the frontend (e.g. http://localhost:3004) |
SPARKY_FITNESS_API_ENCRYPTION_KEY | 64-character hex string — generate with openssl rand -hex 32 |
BETTER_AUTH_SECRET | Long random string — generate with openssl rand -hex 32 |
DB_PATH | Host path for PostgreSQL data (e.g. ./postgresql) |
SERVER_BACKUP_PATH | Host path for server backups (e.g. ./backup) |
SERVER_UPLOADS_PATH | Host path for profile pictures and exercise images (e.g. ./uploads) |
Pull images and start the stack
From inside the
sparkyfitness directory, run:docker compose pulldownloads the latest pre-built images from DockerHub.docker compose up -dstarts all services in detached (background) mode.
Development Environment
Thedocker-helper.sh script in the docker/ directory simplifies switching between development and production modes. Development mode builds images from local source code and mounts the source tree into the containers for live reloading.
Usage
dev | prod
Actions:
| Action | Description |
|---|---|
up | Start services (builds images for dev, pulls images for prod) |
down | Stop and remove containers |
build | Rebuild Docker images |
logs | Tail container logs |
ps | Show container status |
clean | Stop containers and remove images and volumes |
Common commands
Development access URLs
| Service | URL |
|---|---|
| Frontend | http://localhost:8080 |
| Backend API | http://localhost:3010 |
| PostgreSQL | localhost:5432 |
The development Compose file (
docker-compose.dev.yml) uses a .env file at the repository root. Copy docker/.env.example to .env in the repo root and fill in your values before running dev up.Docker Services Overview
Thedocker-compose.prod.yml file defines three core services connected on a private sparkyfitness-network bridge network:
sparkyfitness-db
Image:
postgres:18.3-alpinePostgreSQL database server. Stores all application data. The port is not exposed to the host by default — only other containers on the same network can reach it.sparkyfitness-server
Image:
codewithcj/sparkyfitness_server:latestNode.js backend API server. Runs migrations on first start, manages the app database user, and exposes the REST API internally on port 3010.sparkyfitness-frontend
Image:
codewithcj/sparkyfitness:latestReact frontend served by Nginx. Maps host port 3004 to container port 80. Proxies API requests to the backend internally.Persistent Volumes
Three host paths must be mounted to prevent data loss when containers are recreated. Configure them in your.env file:
| Variable | Default | Purpose |
|---|---|---|
DB_PATH | ./postgresql | PostgreSQL data directory — mounted at /var/lib/postgresql inside the container |
SERVER_BACKUP_PATH | ./backup | Server backup files — mounted at /app/SparkyFitnessServer/backup |
SERVER_UPLOADS_PATH | ./uploads | Profile pictures and exercise images — mounted at /app/SparkyFitnessServer/uploads |
The Garmin Connect microservice (
sparkyfitness-garmin) is optional and is commented out in docker-compose.prod.yml by default. To enable it, open your docker-compose.yml, uncomment the sparkyfitness-garmin service block and its corresponding depends_on entry in sparkyfitness-frontend, then set the required Garmin environment variables.