Building SparkyFitness from source lets you run the application directly on your machine without Docker — useful for contributing to the codebase, experimenting with new features, or deeply customising the application. You will need Node.js, pnpm, and a local PostgreSQL instance. The backend applies database migrations and creates the limited-privilege app user automatically on first start, so the manual setup steps are minimal.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
- Node.js 24 or later — nodejs.org
- pnpm — install with
npm install -g pnpm - PostgreSQL 17 or later — postgresql.org
Steps
Configure environment variables
Copy the example environment file to the repo root and edit it:Linux / macOSWindows (PowerShell)Open
.env and set the following required values:| Variable | Description |
|---|---|
SPARKY_FITNESS_DB_HOST | PostgreSQL host — use localhost for local installs |
SPARKY_FITNESS_DB_NAME | Database name (e.g. sparkyfitness_db) |
SPARKY_FITNESS_DB_USER | Superuser for migrations (e.g. sparky) |
SPARKY_FITNESS_DB_PASSWORD | Superuser password |
SPARKY_FITNESS_APP_DB_USER | App user with limited privileges (e.g. sparky_app) |
SPARKY_FITNESS_APP_DB_PASSWORD | App user password |
SPARKY_FITNESS_FRONTEND_URL | Set to http://localhost:8080 for local builds |
SPARKY_FITNESS_API_ENCRYPTION_KEY | 64-character hex string — generate with openssl rand -hex 32 |
BETTER_AUTH_SECRET | Random secret for session signing — generate with openssl rand -hex 32 |
The default
SPARKY_FITNESS_DB_HOST in the example file is set to a Docker service name (sparkyfitness-db). Change it to localhost for a local (non-Docker) install.Set up PostgreSQL
Create the superuser and database that match your macOS (Homebrew) — omit the Windows — open a terminal and use
.env values. The limited-privilege app user (SPARKY_FITNESS_APP_DB_USER) is created automatically by the server on first startup — you do not need to create it.Linuxsudo -u postgres prefix if your current user already has PostgreSQL superuser rights:psql as the postgres user (adjust the path to match your PostgreSQL installation):Start the backend server
3010. Swagger API docs are available at:Port Summary
| Service | Default URL |
|---|---|
| Frontend (Vite dev server) | http://localhost:8080 |
| Backend API | http://localhost:3010 |
| API Docs (Swagger) | http://localhost:3010/api/api-docs/swagger |
Tips for Development
- Live reloading — the Vite frontend hot-reloads on every file save. The backend (
pnpm start) does not hot-reload by default; restart it after backend changes. - Database migrations run automatically every time the server starts. You do not need to run them manually.
- Environment file location — the server reads
.envfrom the repo root, not from theSparkyFitnessServer/subdirectory. - Switching to Docker — if you later want to use Docker Compose for development, the
docker-helper.sh dev upcommand mounts the same source directories into the containers, giving you live reloading without changing your local setup. See Docker Compose for details.