h2h-prototype/LOCAL_DEVELOPMENT.md

Local Development Guide

Quick Start with Docker (Recommended)

1. Start Local Development Environment

# Start both backend and frontend with hot-reload
docker compose -f docker-compose.dev.yml up --build

# Or run in background
docker compose -f docker-compose.dev.yml up -d --build

2. Access the Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

3. Watch Logs

# View all logs
docker compose -f docker-compose.dev.yml logs -f

# View backend logs only
docker compose -f docker-compose.dev.yml logs -f backend

# View frontend logs only
docker compose -f docker-compose.dev.yml logs -f frontend

4. Stop Development Environment

docker compose -f docker-compose.dev.yml down

# Or stop and remove volumes (resets database)
docker compose -f docker-compose.dev.yml down -v

What's Different from Production?

Setting	Local Development	Production (Coolify)
Backend Port	8000 (mapped to host)	80 (internal only)
Frontend Port	5173 (mapped to host)	80 (internal only)
API URL	http://localhost:8000	https://h2h-backend.host.letsgetnashty.com
WebSocket URL	ws://localhost:8000	wss://h2h-backend.host.letsgetnashty.com
Hot Reload	✅ Enabled (volume mounts)	❌ Disabled (no volume mounts)
File Changes	Live updates	Requires rebuild

Manual Setup (Without Docker)

Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Initialize database with test data
python seed_data.py

# Run development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Access: http://localhost:8000/docs

Frontend Setup

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Access: http://localhost:5173

Test Users

After running seed_data.py, you'll have these test accounts:

Email	Password	Balance
alice@example.com	password123	$1000
bob@example.com	password123	$1000
charlie@example.com	password123	$1000

Development Workflow

Making Changes

1. Edit backend code (Python files in backend/app/)

   • Changes auto-reload if using Docker or uvicorn --reload
   • Check logs for errors

2. Edit frontend code (TypeScript/React files in frontend/src/)

   • Changes instantly appear in browser (Vite HMR)
   • Check browser console for errors

Testing Your Changes

# Test backend API endpoint
curl http://localhost:8000/api/v1/bets

# Test backend with authentication
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/v1/bets/my/active

# Check backend health
curl http://localhost:8000/health

Resetting Database

# Stop containers
docker compose -f docker-compose.dev.yml down -v

# Start fresh (will re-seed on first run)
docker compose -f docker-compose.dev.yml up --build

Or manually:

cd backend
rm -rf data/h2h.db  # Delete database
python seed_data.py  # Recreate with test data

Common Issues

Port Already in Use

Error: Bind for 0.0.0.0:8000 failed: port is already allocated

Solution: Stop other services using those ports:

# Find what's using port 8000
lsof -i :8000

# Stop the process (macOS/Linux)
kill -9 <PID>

# Or use different ports in docker-compose.dev.yml
ports:
  - "8001:8000"  # Map host 8001 to container 8000

Module Not Found (Backend)

Error: ModuleNotFoundError: No module named 'app'

Solution:

# Rebuild backend container
docker compose -f docker-compose.dev.yml up --build backend

Package Not Found (Frontend)

Error: npm error enoent Could not read package.json

Solution:

# Rebuild frontend container
docker compose -f docker-compose.dev.yml up --build frontend

Database Locked

Error: database is locked

Solution: SQLite doesn't handle concurrent writes well. Restart:

docker compose -f docker-compose.dev.yml restart backend

Hot Reload Not Working

Issue: Changes not appearing

Solution:

1. Check volume mounts are working:

   docker compose -f docker-compose.dev.yml exec backend ls -la /app
   

2. Restart containers:

   docker compose -f docker-compose.dev.yml restart
   

IDE Setup

VS Code

Recommended Extensions:

• Python (ms-python.python)
• Pylance (ms-python.vscode-pylance)
• ES Lint (dbaeumer.vscode-eslint)
• Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)

Settings (.vscode/settings.json):

{
  "python.linting.enabled": true,
  "editor.formatOnSave": true,
  "python.analysis.typeCheckingMode": "basic"
}

Python Type Checking

cd backend
source venv/bin/activate
mypy app/

Frontend Type Checking

cd frontend
npm run type-check  # If configured in package.json

Debugging

Backend Debugging

Add breakpoints in your IDE or use:

import pdb; pdb.set_trace()  # Python debugger

Frontend Debugging

Use browser DevTools:

• Console: View logs and errors
• Network: Inspect API calls
• React DevTools: Inspect component state

File Watching

Docker uses file watching to detect changes. If you have a large codebase:

macOS: Increase file watch limit:

# Add to ~/.bash_profile or ~/.zshrc
export DOCKER_MAX_FILE_WATCHES=524288

Linux: Increase inotify watches:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Production Preview (Local)

To test the production build locally:

# Use production docker-compose (port 80 mapping)
docker compose up --build

# Access via:
# Backend: http://localhost (if mapped)
# Frontend: http://localhost (if mapped)

Note: You may need to add port mappings to test on macOS/Windows:

ports:
  - "80:80"  # Requires sudo/admin on port 80
  # Or use alternative ports:
  - "8080:80"  # Access via http://localhost:8080

Switching Between Dev and Production

Local Development:

docker compose -f docker-compose.dev.yml up

Production Build (Local):

docker compose up

Production Deployment (Coolify):

git push  # Coolify auto-deploys

---

Happy coding! 🚀