paragliding/DEV_SETUP.md

Local Development Setup

This guide shows how to run the application locally for faster development iteration.

Overview

Instead of running everything in containers, you can run just PostgreSQL in a container and run the backend (Go) and frontend (Next.js) natively on your machine. This provides:

• ✨ Faster hot-reload and rebuild times
• 🔧 Better debugging experience
• 📦 Smaller resource footprint
• 🚀 Quicker iteration cycles

Prerequisites

• Go 1.24+ installed
• Node.js 18+ and npm (or Bun)
• Podman or Docker (for PostgreSQL only)

Quick Start

Option 1: Single Command - Everything! (Recommended)

# Setup AND start all services in background
./dev.sh --start

That's it! This one command:

• ✓ Starts PostgreSQL (if not running)
• ✓ Creates .env files (if they don't exist)
• ✓ Runs database migrations (if needed)
• ✓ Starts backend in background
• ✓ Starts frontend in background

View logs: tail -f backend.log or tail -f frontend.log Stop services: ./dev.sh --stop Check status: ./dev.sh --status

Option 2: Setup Only (Manual Start)

# Run setup without starting services
./dev.sh

# Then in separate terminals:
# Terminal 1 - Backend
make run-backend

# Terminal 2 - Frontend
make run-frontend

The dev.sh script is idempotent - you can run it multiple times safely. It will:

• ✓ Check if PostgreSQL is already running (won't restart if running)
• ✓ Create .env files only if they don't exist
• ✓ Run migrations only if needed
• ✓ Skip steps that are already complete
• ✓ Detect if services are already running (won't duplicate)

Option 3: Using Make

# Start PostgreSQL and run migrations
make dev-local

# Then in separate terminals:
# Terminal 1 - Backend
make run-backend

# Terminal 2 - Frontend
make run-frontend

Option 4: Manual Setup

1. Start PostgreSQL

   make dev-db
   

2. Configure Backend

   # Copy example env file
   cp backend/.env.example backend/.env
   
   # Edit if needed (defaults should work)
   # vim backend/.env
   

3. Run Database Migrations

   make migrate-up DATABASE_URL="postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable"
   

4. Start Backend (in one terminal)

   cd backend
   go run ./cmd/api
   

   Backend will be available at: http://localhost:8080

5. Start Frontend (in another terminal)

   cd frontend
   npm run dev
   # or with bun:
   # bun run dev
   

   Frontend will be available at: http://localhost:3000

Configuration

Backend Environment Variables

The backend uses environment variables defined in backend/.env:

DATABASE_URL=postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable
PORT=8080
LOCATION_LAT=32.8893              # Torrey Pines Gliderport
LOCATION_LON=-117.2519
LOCATION_NAME=Torrey Pines Gliderport
TIMEZONE=America/Los_Angeles
FETCH_INTERVAL=15m
CACHE_TTL=10m

Frontend Environment Variables

The frontend uses frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8080/api/v1

Database Management

# Start PostgreSQL
make dev-db

# Stop PostgreSQL
make dev-db-down

# Run migrations up
make migrate-up DATABASE_URL="postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable"

# Run migrations down
make migrate-down DATABASE_URL="postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable"

# Create a new migration
make migrate-create name=add_new_table

Using Bun Instead of npm

If you prefer Bun for faster package installation and execution:

cd frontend

# Install dependencies
bun install

# Run dev server
bun run dev

# Run build
bun run build

Switching Between Local and Container Development

To Local Development:

# Stop all containers
make dev-down

# Start only PostgreSQL
make dev-db

# Run apps locally (separate terminals)
make run-backend
make run-frontend

Back to Full Container Development:

# Stop local PostgreSQL
make dev-db-down

# Start all services in containers
make dev

Troubleshooting

Backend won't connect to PostgreSQL

• Ensure PostgreSQL is running: podman ps or docker ps
• Check connection string in backend/.env
• Verify PostgreSQL is healthy: podman logs paragliding-postgres

Frontend can't reach backend

• Ensure backend is running on port 8080
• Check NEXT_PUBLIC_API_URL in frontend/.env.local
• Verify backend health: curl http://localhost:8080/api/v1/health

Port already in use

• Backend (8080): Change PORT in backend/.env
• Frontend (3000): Next.js will prompt for alternative port automatically
• PostgreSQL (5432): Change port mapping in docker-compose.dev.yml

Hot Reload & Live Development

• Frontend: Next.js automatically hot-reloads on file changes
• Backend: For auto-reload, install Air:

  go install github.com/air-verse/air@latest
  cd backend
  air
  

  Air config is already set up in backend/.air.toml

Running Tests

# Backend tests
make test-backend

# Frontend tests
make test-frontend

API Endpoints

Once running, you can access:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080/api/v1
• Health Check: http://localhost:8080/api/v1/health
• Current Weather: http://localhost:8080/api/v1/weather/current
• Forecast: http://localhost:8080/api/v1/weather/forecast