Installation Guide

Installation Guide 🚀

This guide will help you set up Running Page 2.0 on your local machine or deploy it to production.

🎯 Prerequisites

Required

• Node.js 18+ (LTS recommended)
• npm or yarn package manager
• Git for version control

Optional (for full functionality)

• Strava Account - For activity data sync
• Mapbox Account - For map generation
• Vercel Account - For easy deployment

🚀 Quick Start Options

Option 1: One-Click Deploy (Recommended)

1. Click the deploy button above
2. Connect your GitHub account
3. Configure environment variables (see Configuration)
4. Deploy and enjoy!

Option 2: Manual Installation

Step 1: Clone Repository

git clone https://github.com/oiahoon/running2.0.git
cd running2.0

Step 2: Install Dependencies

# Navigate to web app
cd apps/web

# Install dependencies
npm install

Step 3: Environment Setup

# Copy environment template
cp .env.example .env.local

# Edit environment variables
nano .env.local

Step 4: Database Setup

# Initialize database (if needed)
npm run db:init

# Run migrations
npm run migrate

Step 5: Start Development Server

npm run dev

Visit http://localhost:3000 to see your Running Page 2.0!

⚙️ Environment Configuration

Required Variables

Create .env.local in /apps/web/:

# User Information
NEXT_PUBLIC_USER_NAME="Your Full Name"
NEXT_PUBLIC_GITHUB_USERNAME="your-github-username"
NEXT_PUBLIC_USER_EMAIL="[email protected]"

# Database
DATABASE_PATH="./data/running_page_2.db"

Optional Variables

# Maps (for interactive features)
NEXT_PUBLIC_MAPBOX_TOKEN="your_mapbox_token_here"

# Performance Optimization
NEXT_PUBLIC_PREFER_CDN=true
NEXT_PUBLIC_PREFER_LOCAL_MAPS=true

🔄 Data Sync Setup

GitHub Actions Secrets

For automatic data sync, configure these secrets in your GitHub repository:

# Strava API (Required for data sync)
STRAVA_CLIENT_ID="your_strava_client_id"
STRAVA_CLIENT_SECRET="your_strava_client_secret"
STRAVA_REFRESH_TOKEN="your_strava_refresh_token"

# Mapbox (Required for map generation)
MAPBOX_TOKEN="your_mapbox_token_without_url_restrictions"

Strava API Setup

1. Create Strava App

   • Visit Strava Developers
   • Create new application
   • Note Client ID and Client Secret

2. Get Refresh Token

   # Use the test script
   cd scripts
   python test-strava-permissions.py

3. Configure GitHub Secrets

   • Go to your repository Settings → Secrets
   • Add the three Strava variables

🗺️ Map System Setup

Mapbox Configuration

1. Create Mapbox Account

   • Visit Mapbox
   • Create free account (50,000 requests/month)

2. Create Tokens

   • Public Token: For web app (with URL restrictions)
   • Secret Token: For GitHub Actions (no URL restrictions)

3. Configure Tokens

   # In .env.local (public token)
   NEXT_PUBLIC_MAPBOX_TOKEN="pk.your_public_token"
   
   # In GitHub Secrets (secret token)
   MAPBOX_TOKEN="sk.your_secret_token"

📦 Build and Deploy

Local Build

# Build for production
npm run build

# Start production server
npm run start

Vercel Deployment

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Docker Deployment

# Build Docker image
docker build -t running-page-2.0 .

# Run container
docker run -p 3000:3000 running-page-2.0

🔧 Development Scripts

# Development
npm run dev          # Start dev server
npm run build        # Production build
npm run start        # Production server

# Database
npm run db:init      # Initialize database
npm run migrate      # Run migrations
npm run prepare-db   # Prepare for Vercel

# Testing
npm run type-check   # TypeScript validation
npm run lint         # Code linting

🐛 Troubleshooting

Common Issues

Port 3000 already in use?

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
npm run dev -- -p 3001

Database not found?

# Check database path
ls -la apps/web/data/

# Reinitialize if needed
npm run db:init

Maps not loading?

• Check Mapbox token validity
• Verify URL restrictions
• Check browser console for errors

Build failing?

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
npm run build

Getting Help

• 📚 Check the Troubleshooting wiki page
• 🐛 Open an issue
• 💬 Start a discussion

✅ Verification

After installation, verify everything works:

1. ✅ App loads - Visit http://localhost:3000
2. ✅ Dashboard shows - Basic UI components render
3. ✅ Activities page - Pagination and filtering work
4. ✅ Maps display - Static maps or Mapbox fallback
5. ✅ Stats page - Charts and analytics render

🎉 Next Steps

• Configure your environment variables
• Customize the cyberpunk theme
• Set up Strava data sync
• Deploy to production

Welcome to the cyberpunk running revolution! 🏃‍♂️⚡