Codakey
Play
← Back to SparkyFitness

How to Deploy & Use SparkyFitness

SparkyFitness Deployment & Usage Guide

1. Prerequisites

Runtime & Tools:

  • Docker & Docker Compose (recommended for production deployment)
  • Node.js 18+ (for development builds)
  • npm or yarn package manager
  • PostgreSQL 14+ database (included in Docker setup)
  • Redis (for caching and background jobs)

Mobile Development (if building apps):

  • Xcode 15+ (for iOS development)
  • Android Studio (for Android development)
  • React Native CLI environment setup

Optional Integrations:

  • Apple Developer Account (for iOS HealthKit integration)
  • Google Cloud Account (for Android Health Connect integration)
  • Fitbit/Garmin/Withings Developer Accounts (for device integrations)
  • OpenAI API Key (for AI features - beta)

2. Installation

Docker Compose (Recommended for Production)

# 1. Create project directory
mkdir sparkyfitness && cd sparkyfitness

# 2. Download production Docker files
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

# 3. Review and edit environment variables
nano .env  # or use your preferred editor

# 4. Pull and start containers
docker compose pull
docker compose up -d

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

Manual Installation (Development)

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

# 2. Install backend dependencies
cd backend
npm install

# 3. Install frontend dependencies
cd ../frontend
npm install

# 4. Install mobile app dependencies (optional)
cd ../mobile
npm install

# 5. Set up environment variables (see Configuration section)
cp .env.example .env

3. Configuration

Essential Environment Variables

Create a .env file in your project root with these variables:

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/sparkyfitness
REDIS_URL=redis://localhost:6379

# Server Configuration
PORT=3000
NODE_ENV=production
API_URL=http://localhost:3000
WEB_URL=http://localhost:8080

# Security
JWT_SECRET=your-super-secret-jwt-key-change-this
SESSION_SECRET=your-session-secret-change-this
ENCRYPTION_KEY=your-32-character-encryption-key

# Email (optional, for notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# AI Features (optional beta)
OPENAI_API_KEY=sk-your-openai-api-key
AI_ENABLED=false

# Health Integrations (platform-specific)
HEALTHKIT_ENABLED=true  # iOS
HEALTH_CONNECT_ENABLED=true  # Android

Mobile App Configuration

For mobile apps, configure platform-specific settings:

iOS (HealthKit):

  • Enable HealthKit capability in Xcode
  • Add NSHealthShareUsageDescription and NSHealthUpdateUsageDescription to Info.plist
  • Configure supported HealthKit types from src/services/healthkit/index.ts

Android (Health Connect):

  • Add Health Connect permissions to AndroidManifest.xml
  • Configure supported record types from src/services/healthconnect/dataTransformation.ts

Database Setup

# If using Docker, database is automatically initialized
# For manual setup, run migrations:
cd backend
npm run db:migrate
npm run db:seed  # Optional: seed with sample data

4. Build & Run

Development Mode

# Start backend server
cd backend
npm run dev

# Start frontend development server (in separate terminal)
cd frontend
npm run dev

# Start mobile app (in separate terminal)
cd mobile
npm run ios  # or npm run android

Production Build

# Build backend
cd backend
npm run build

# Build frontend
cd frontend
npm run build

# Build mobile apps
cd mobile
npm run build:ios  # Requires Xcode
npm run build:android  # Requires Android SDK

# Start production server
cd backend
npm start

Using Docker for Local Development

# Development environment with hot reload
docker compose -f docker-compose.dev.yml up

# Production-like environment
docker compose -f docker-compose.prod.yml up

5. Deployment

Platform Recommendations

Self-Hosted Options:

  1. Docker on VPS (DigitalOcean, Linode, AWS EC2)
  2. Kubernetes (for scalable deployments)
  3. Railway.app or Render.com (managed platforms)

Mobile App Distribution:

  • iOS: TestFlight for beta, App Store for production
  • Android: Internal testing track, Google Play Store

Docker Deployment on VPS

# 1. SSH into your server
ssh user@your-server-ip

# 2. Install Docker and Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo apt-get install docker-compose-plugin

# 3. Clone and configure SparkyFitness
git clone https://github.com/CodeWithCJ/SparkyFitness.git
cd SparkyFitness
nano .env  # Configure production settings

# 4. Start with Docker Compose
docker compose -f docker-compose.prod.yml up -d

# 5. Set up reverse proxy (nginx example)
sudo apt install nginx
sudo nano /etc/nginx/sites-available/sparkyfitness

Example nginx configuration:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
    
    location /api {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Railway.app Deployment

# 1. Install Railway CLI
npm i -g @railway/cli

# 2. Login and initialize
railway login
railway init

# 3. Link to SparkyFitness project
railway link

# 4. Set environment variables
railway variables set DATABASE_URL=postgresql://...
railway variables set JWT_SECRET=...

# 5. Deploy
railway up

6. Troubleshooting

Common Issues

1. Database Connection Errors

# Check if PostgreSQL is running
docker ps | grep postgres

# Test connection
docker exec -it sparkyfitness-db-1 psql -U postgres -d sparkyfitness

# Reset database (development only)
npm run db:reset

2. HealthKit/Health Connect Permissions

  • iOS: Ensure HealthKit entitlements are properly configured in Xcode
  • Android: Verify Health Connect is installed and permissions are granted
  • Check device logs: adb logcat | grep HealthConnect or Xcode console

3. Mobile App Build Failures

# Clear caches
cd mobile
npm run clean
rm -rf node_modules
npm install

# iOS specific
cd ios
pod deintegrate
pod install

# Android specific
cd android
./gradlew clean

4. Docker Container Issues

# Check container logs
docker compose logs -f backend
docker compose logs -f frontend

# Restart services
docker compose restart

# Rebuild containers
docker compose build --no-cache
docker compose up -d

5. AI Features Not Working

  • Verify OpenAI API key is valid and has credits
  • Check if AI_ENABLED=true in environment
  • Review backend logs for API errors

6. Sync Issues with Health Devices

  • Verify OAuth credentials for Fitbit/Garmin/Withings
  • Check sync schedules in admin panel
  • Review src/services/healthkit/index.ts for supported types
  • Ensure proper date formatting in data transformations

Getting Help

Debugging Tips

  1. Enable verbose logging by setting LOG_LEVEL=debug in .env
  2. Check browser console for frontend errors
  3. Monitor network requests for API issues
  4. Review mobile device logs using React Native debugger
  5. Test individual services using the provided seed data utilities in src/services/seedHealthData.ts
← Project overviewView alternatives to SparkyFitness →