init

2026-01-03 14:16:16 -08:00
commit 1f0e678d47
71 changed files with 16127 additions and 0 deletions
--- a/DEV_SETUP.md
+++ b/DEV_SETUP.md
@@ -0,0 +1,243 @@
+# 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)
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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**
+   ```bash
+   make dev-db
+   ```
+
+2. **Configure Backend**
+   ```bash
+   # Copy example env file
+   cp backend/.env.example backend/.env
+
+   # Edit if needed (defaults should work)
+   # vim backend/.env
+   ```
+
+3. **Run Database Migrations**
+   ```bash
+   make migrate-up DATABASE_URL="postgres://dev:devpass@localhost:5432/paragliding?sslmode=disable"
+   ```
+
+4. **Start Backend** (in one terminal)
+   ```bash
+   cd backend
+   go run ./cmd/api
+   ```
+   Backend will be available at: http://localhost:8080
+
+5. **Start Frontend** (in another terminal)
+   ```bash
+   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`:
+
+```bash
+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`:
+
+```bash
+NEXT_PUBLIC_API_URL=http://localhost:8080/api/v1
+```
+
+## Database Management
+
+```bash
+# 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:
+
+```bash
+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:
+```bash
+# 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:
+```bash
+# 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:
+  ```bash
+  go install github.com/air-verse/air@latest
+  cd backend
+  air
+  ```
+  Air config is already set up in `backend/.air.toml`
+
+## Running Tests
+
+```bash
+# 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