strat-gameplay-webapp/NATIVE_DEV_SETUP.md

# Native Development Setup

Fast development workflow with instant startup, hot-reload, and no Docker rebuilds.

## Why Native Development?

**Problem**: Docker production builds take 3-5 minutes to rebuild on every change.

**Solution**: Run backend and frontend natively on your machine, use Docker only for Redis.

**Benefits**:
- ⚡ **Instant startup** (seconds, not minutes)
- 🔥 **Hot-reload** on file changes (backend + frontend)
- 🐛 **Native debugging** (attach debugger directly)
- 💾 **No rebuild overhead** (just save and refresh)

## Prerequisites

### 1. Install Dependencies

```bash
# UV (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Node.js 22+ (if not already installed)
# https://nodejs.org/

# Docker (for Redis only)
# Already installed if you've been using ./start.sh
```

### 2. Configure Discord OAuth (One-Time Setup)

You need to add `http://localhost:8000` as an allowed redirect URI in your Discord application.

**Steps**:

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Select your application (ID: `1441192438055178420`)
3. Navigate to **OAuth2** → **General**
4. Under **Redirects**, click **Add Redirect**
5. Add: `http://localhost:8000/api/auth/discord/callback/server`
6. Click **Save Changes**

**Your redirect URIs should now include**:
- ✅ `http://localhost:8000/api/auth/discord/callback/server` (dev)
- ✅ `https://gameplay-demo.manticorum.com/api/auth/discord/callback/server` (prod)

## Quick Start

### Option 1: New Native Dev Script (Recommended)

```bash
# Start everything (instant, hot-reload)
./dev-native.sh start

# View logs
./dev-native.sh logs

# Stop everything
./dev-native.sh stop

# Restart everything
./dev-native.sh restart
```

**What it does**:
1. Starts Redis in Docker (seconds)
2. Starts backend natively with `uv run uvicorn --reload` (instant)
3. Starts frontend natively with `npm run dev` (instant)

**No rebuilds. Ever.**

### Option 2: Manual Setup (Full Control)

If you prefer to run each service in separate terminals:

```bash
# Terminal 1: Redis (Docker)
docker compose up redis

# Terminal 2: Backend (native)
cd backend
uv run uvicorn app.main:socket_app --host 0.0.0.0 --port 8000 --reload

# Terminal 3: Frontend (native)
cd frontend-sba
npm run dev
```

## What Changed?

### 1. Cookie Security Flags Now Respect `APP_ENV`

**Before**:
- Cookies always used `Secure=true` + `SameSite=none`
- Required HTTPS (prod URLs only)
- Broke on localhost

**After** (in `backend/app/utils/cookies.py`):
- `APP_ENV=development` → `Secure=false` + `SameSite=lax` (works on localhost)
- `APP_ENV=production` → `Secure=true` + `SameSite=none` (works cross-domain)

### 2. Environment Files Already Configured

The `.env.dev` files already have localhost URLs:

**Backend** (`backend/.env.dev`):
```bash
DISCORD_SERVER_REDIRECT_URI=http://localhost:8000/api/auth/discord/callback/server
FRONTEND_URL=http://localhost:3000
CORS_ORIGINS=["http://localhost:3000","http://localhost:3001"]
```

**Frontend** (`frontend-sba/.env.dev`):
```bash
NUXT_PUBLIC_API_URL=http://localhost:8000
NUXT_PUBLIC_WS_URL=http://localhost:8000
NUXT_PUBLIC_DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
```

The `dev-native.sh` script automatically copies these to `.env` when you run it.

## Usage Patterns

### Typical Development Flow

```bash
# Start once
./dev-native.sh start

# Make changes to backend/frontend code
# Changes auto-reload instantly!

# View logs if needed
./dev-native.sh logs

# Stop when done
./dev-native.sh stop
```

### Debugging

**Backend** (Python):
```bash
# Stop the background process
./dev-native.sh stop

# Run backend in foreground with debugger
cd backend
uv run python -m debugpy --listen 5678 -m uvicorn app.main:socket_app --host 0.0.0.0 --port 8000 --reload

# Attach your IDE's debugger to localhost:5678
```

**Frontend** (Vue):
```bash
# Browser DevTools work automatically with HMR
# Or use Vue DevTools browser extension
```

### Switching Between Native and Docker

**To Native**:
```bash
# Stop Docker services
./start.sh stop

# Start native
./dev-native.sh start
```

**To Docker** (for testing prod builds):
```bash
# Stop native
./dev-native.sh stop

# Start Docker prod
./start.sh prod
```

## Troubleshooting

### Discord OAuth Still Fails

**Symptoms**: Redirect to Discord works, but callback fails with "Invalid redirect_uri"

**Fixes**:
1. Verify you added `http://localhost:8000/api/auth/discord/callback/server` to Discord app
2. Check `backend/.env` has `APP_ENV=development`
3. Check `backend/.env` has `DISCORD_SERVER_REDIRECT_URI=http://localhost:8000/api/auth/discord/callback/server`
4. Restart backend: `./dev-native.sh restart`

### Backend Won't Start

**Check logs**:
```bash
tail -f .logs/backend.log
```

**Common issues**:
- Port 8000 already in use: `lsof -i :8000` (kill the process)
- Missing Python dependencies: `cd backend && uv sync`
- Database connection error: Check PostgreSQL is running

### Frontend Won't Start

**Check logs**:
```bash
tail -f .logs/frontend.log
```

**Common issues**:
- Port 3000 already in use: `lsof -i :3000` (kill the process)
- Missing node_modules: `cd frontend-sba && npm ci`
- Build error: Delete `.nuxt` and `.output` folders, restart

### Redis Connection Error

**Symptoms**: Backend logs show "Redis connection refused"

**Fix**:
```bash
# Check Redis status
docker compose ps redis

# Restart Redis if needed
docker compose restart redis
```

## Performance Comparison

| Method | Initial Start | After Code Change | Rebuild Time |
|--------|--------------|-------------------|--------------|
| **Native Dev** | 5-10 seconds | Instant (HMR) | Never |
| Docker Dev | 30-60 seconds | Instant (volume mount) | 2-3 minutes |
| Docker Prod | **3-5 minutes** | **3-5 minutes** | **3-5 minutes** |

## Notes

- **Redis still uses Docker** (lightweight, starts in seconds)
- **PostgreSQL** is external (on `10.10.0.42`), not affected
- `.pids/` and `.logs/` directories are gitignored
- Backend uses `uvicorn --reload` (watches Python files)
- Frontend uses `nuxt dev` (HMR for Vue files)

## When to Use Docker Prod Mode

Use `./start.sh prod` when:
- Testing production builds before deployment
- Debugging Docker-specific issues
- Testing HTTPS/cross-origin scenarios
- Running integration tests

For day-to-day development, use `./dev-native.sh start` for maximum speed.