productionize

CLAUDE.md

@@ -111,6 +111,48 @@ FRONTEND_PORT=4000 docker compose up
 - Named volume for `node_modules` to avoid host/container conflicts
 - Health check on backend before starting frontend
 
+### Docker Production (Single Container)
+
+For production deployment with a single URL serving both frontend and backend:
+
+```bash
+# Build production image (multi-stage: builds React, copies to Flask static/)
+docker build -t trivia-app:latest .
+
+# Run with production compose file
+docker compose -f docker-compose.production.yml up -d
+
+# Or run standalone container
+docker run -d \
+  -p 5001:5001 \
+  -v trivia-db:/app/backend/instance \
+  -v trivia-images:/app/backend/static/images \
+  -v trivia-audio:/app/backend/static/audio \
+  --env-file .env.production \
+  trivia-app:latest
+
+# View logs
+docker compose -f docker-compose.production.yml logs -f
+
+# Run migrations
+docker compose -f docker-compose.production.yml exec backend uv run flask db upgrade
+```
+
+**Production Architecture:**
+- Multi-stage `Dockerfile`: Stage 1 builds React frontend, Stage 2 runs Flask with built frontend
+- Single Flask server serves both React SPA and API endpoints
+- All requests go to same origin (e.g., `https://trivia.torrtle.co`)
+- React uses relative URLs (`/api/*`, `/socket.io`) - no proxy needed
+- Flask routing: API requests go to blueprints, all other routes serve `index.html` for React Router
+- Typically deployed behind nginx/Caddy reverse proxy for HTTPS/SSL
+- Volumes persist database, images, and audio files
+
+**Environment:**
+- Copy `.env.production.example` to `.env.production` and configure
+- Set `CORS_ORIGINS` to your domain (e.g., `https://trivia.torrtle.co`)
+- Set `SESSION_COOKIE_SECURE=true` for HTTPS
+- Configure OIDC URLs to match your domain
+
 ## Architecture
 
 ### Application Factory Pattern