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

# 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
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)

# 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:

# 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):

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):

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

# 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):

# 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):

# Browser DevTools work automatically with HMR
# Or use Vue DevTools browser extension

Switching Between Native and Docker

To Native:

# Stop Docker services
./start.sh stop

# Start native
./dev-native.sh start

To Docker (for testing prod builds):

# 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:

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:

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:

# 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.