Getting Started

SparkyFitness is a comprehensive fitness tracking application built with React 18 + TypeScript + Vite frontend and Node.js/Express backend, using PostgreSQL with Row Level Security.

Prerequisites

Before you begin, ensure you have the following installed:

  • Docker & Docker Compose: Essential for running SparkyFitness in containerized environments.
  • Git: For cloning the SparkyFitness repository.

For Local Development (without Docker)

  • Node.js 18+ and npm: The JavaScript runtime and package manager.
  • PostgreSQL 15+: The database server.
  • Git: For version control.

The fastest way to get SparkyFitness running is using our Docker helper script:

# Clone the repository
git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness

# Copy environment template
cp docker/.env.example .env

# Start development environment (with live reloading)
./docker/docker-helper.sh dev up

# Access the application at http://localhost:8080

Docker Helper Script

The Docker helper script provides an easy interface for managing your development and production environments:

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

# Start development environment
./docker/docker-helper.sh dev up

# Start production environment  
./docker/docker-helper.sh prod up

# View logs
./docker/docker-helper.sh logs

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

# Clean up everything
./docker/docker-helper.sh clean

Available Commands

  • dev up - Start development environment with live reloading
  • prod up - Start production environment with optimized builds
  • down - Stop all services
  • logs [service] - View logs for all services or specific service
  • clean - Remove all containers, networks, and volumes
  • build - Rebuild all images
  • restart [service] - Restart all services or specific service

Environment Setup

Development Environment

Perfect for active development with live reloading:

# Start development stack
./docker/docker-helper.sh dev up

# Services available:
# - Frontend: http://localhost:8080 (live reload)
# - Backend: http://localhost:3010 (direct access)
# - Database: localhost:5432 (direct access)

Development Features

  • Live Reloading: Both frontend and backend automatically reload on file changes
  • Volume Mounts: Your local code is mounted into containers for instant updates
  • Direct Database Access: Connect directly to PostgreSQL for debugging
  • Development Dependencies: All dev tools and debugging capabilities enabled

Production Environment

Optimized builds for deployment testing:

# Start production stack
./docker/docker-helper.sh prod up

# Service available:
# - Application: http://localhost:3004 (nginx proxy)

Production Features

  • Optimized Builds: Minified frontend and production-ready backend
  • Nginx Proxy: Single entry point with load balancing and static file serving
  • Environment Isolation: Separate network and security configurations
  • DockerHub Images: Uses pre-built images for faster deployment

Local Development (without Docker)

If you prefer to run the application locally without Docker:

Database Setup

  1. Install PostgreSQL 15+
  2. Create database: 
    CREATE DATABASE sparkyfitness;
CREATE USER sparky WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE sparkyfitness TO sparky;

Backend Setup

# Navigate to server directory
cd SparkyFitnessServer

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your database credentials

# Run database migrations
npm run migrate

# Start development server
npm run dev

Frontend Setup

# Navigate to project root
cd ..

# Install dependencies
npm install

# Start development server
npm run dev

Environment Variables

Copy the environment template and configure according to your setup:

cp docker/.env.example .env

Key variables to configure:

Database Configuration

  • DATABASE_URL - PostgreSQL connection string
  • DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD - Individual database settings

Application Settings

  • PORT - Backend server port (default: 3010)
  • NODE_ENV - Environment mode (development/production)
  • JWT_SECRET - Secret key for JWT token signing

Frontend Configuration

  • SPARKY_FITNESS_SERVER_HOST - Backend service connection
  • SPARKY_FITNESS_SERVER_PORT - Backend service port

AI Integration

  • OPENAI_API_KEY - OpenAI API key for AI features
  • GOOGLE_AI_API_KEY - Google Gemini API key
  • ANTHROPIC_API_KEY - Anthropic Claude API key

Manual Docker Compose

If you prefer to use Docker Compose directly:

# Production deployment
docker-compose -f docker/docker-compose.prod.yml up -d

# Development with live reloading
docker-compose -f docker/docker-compose.dev.yml up

# Stop services
docker-compose down

# View logs
docker-compose logs -f [service_name]

Configuration Files

The Docker setup includes several configuration files:

Dockerfiles

  • Dockerfile.frontend - Multi-stage frontend build
  • Dockerfile.backend - Backend Node.js application
  • docker/nginx.conf.template - Nginx configuration template

Compose Files

  • docker-compose.dev.yml - Development environment
  • docker-compose.prod.yml - Production environment

Configuration

  • docker/.env.example - Environment variables template
  • docker/docker-entrypoint.sh - Environment variable substitution script
  • docker/docker-helper.sh - Management script with validation

Next Steps

Once you have the application running:

  1. Explore the Application: Visit http://localhost:8080 (dev) or http://localhost:3004 (prod)
  2. Create an Account: Register a new user account
  3. Check the API: Backend API is available at http://localhost:3010/api (dev only)
  4. Review the Architecture: See our Architecture Guide
  5. Start Contributing: Check out our Contributing Guide

Common Issues

Port Conflicts

If you encounter port conflicts, check what's using the required ports:

# Check port usage
lsof -i :8080  # Frontend
lsof -i :3010  # Backend  
lsof -i :5432  # Database

Database Connection Issues

Ensure PostgreSQL is running and credentials are correct in your .env file.

Permission Issues

Make sure Docker has proper permissions and your user is in the docker group:

sudo usermod -aG docker $USER
# Log out and back in

For more detailed troubleshooting, see our Troubleshooting Guide.

Table of Contents