Commit

old/API_SUBDOMAIN_MIGRATION.md

@@ -0,0 +1,143 @@
+# API Subdomain Migration
+
+## Overview
+Migrated from proxying API requests through PWA nginx to a dedicated API subdomain. This is a cleaner architecture with better separation of concerns.
+
+## Changes Made
+
+### 1. **Architecture Change**
+**Old:**
+```
+Browser → Traefik → PWA nginx → API (internal proxy)
+```
+
+**New:**
+```
+Browser → Traefik → API (direct)
+Browser → Traefik → PWA (static files only)
+```
+
+### 2. **docker-compose.yml**
+- Added Traefik labels to `echoes_of_the_ashes_api` service
+- Exposed API on subdomain: `api.echoesoftheashgame.patacuack.net`
+- Added `traefik` network to API service
+- Added build args to PWA service for `VITE_API_URL`
+
+### 3. **nginx.conf**
+- Removed `/api/` proxy location block
+- Removed `/ws/` proxy location block  
+- nginx now only serves static PWA files
+
+### 4. **Dockerfile.pwa**
+- Added `ARG VITE_API_URL` build argument
+- Default value: `https://api.echoesoftheashgame.patacuack.net`
+- Sets environment variable during build
+
+### 5. **pwa/src/services/api.ts**
+- Changed baseURL to use `VITE_API_URL` environment variable
+- Falls back to `https://api.echoesoftheashgame.patacuack.net` in production
+- Falls back to `http://localhost:8000` in development
+
+### 6. **pwa/src/hooks/useGameWebSocket.ts**
+- Updated WebSocket URL to use same API subdomain
+- Converts `https://api.echoesoftheashgame.patacuack.net` to `wss://api.echoesoftheashgame.patacuack.net`
+
+### 7. **pwa/src/vite-env.d.ts**
+- Added `VITE_API_URL` to TypeScript environment types
+
+## DNS Configuration Required
+
+⚠️ **IMPORTANT:** You need to add a DNS A record:
+
+```
+Host: api.echoesoftheashgame
+Points to: <your server IP>
+```
+
+Or if using CNAME:
+```
+Host: api.echoesoftheashgame
+CNAME: echoesoftheashgame.patacuack.net
+```
+
+## Benefits
+
+1. **Cleaner Architecture**
+   - Separation of concerns (PWA vs API)
+   - No nginx proxy complexity
+   - Direct Traefik routing to API
+
+2. **Better Performance**
+   - One less hop (no nginx proxy)
+   - Direct TLS termination at Traefik
+   - WebSocket connections more stable
+
+3. **Easier Debugging**
+   - Clear separation in logs
+   - Distinct URLs for frontend vs backend
+   - Better CORS visibility
+
+4. **Scalability**
+   - Can scale API and PWA independently
+   - Can add load balancing per service
+   - Can deploy to different servers if needed
+
+## Deployment Steps
+
+```bash
+# Build with new configuration
+docker compose build echoes_of_the_ashes_api echoes_of_the_ashes_pwa
+
+# Deploy both services
+docker compose up -d echoes_of_the_ashes_api echoes_of_the_ashes_pwa
+
+# Check Traefik picked up the new routes
+docker compose logs echoes_of_the_ashes_api | grep -i traefik
+
+# Wait for TLS certificate generation (30-60 seconds)
+# Test API endpoint
+curl https://api.echoesoftheashgame.patacuack.net/health
+
+# Test PWA loads
+curl -I https://echoesoftheashgame.patacuack.net
+```
+
+## API Endpoints
+
+All API endpoints are now at:
+- `https://api.echoesoftheashgame.patacuack.net/api/auth/login`
+- `https://api.echoesoftheashgame.patacuack.net/api/auth/register`
+- `https://api.echoesoftheashgame.patacuack.net/api/game/state`
+- `https://api.echoesoftheashgame.patacuack.net/api/game/profile`
+- etc.
+
+**Note:** API routes have `/api/` prefix in FastAPI
+
+WebSocket endpoint:
+- `wss://api.echoesoftheashgame.patacuack.net/ws/game/{token}`
+
+**Note:** WebSocket routes do NOT have `/api/` prefix
+
+## Rollback Plan
+
+If needed, revert by:
+1. Remove Traefik labels from API service
+2. Restore nginx proxy locations for `/api/` and `/ws/`
+3. Change `VITE_API_URL` back to PWA domain
+4. Rebuild PWA
+
+## Testing Checklist
+
+- [ ] DNS resolves for `api.echoesoftheashgame.patacuack.net`
+- [ ] API health endpoint returns 200
+- [ ] Login works from PWA
+- [ ] WebSocket connects successfully
+- [ ] Game functionality works end-to-end
+- [ ] TLS certificate valid on API subdomain
+
+## Notes
+
+- PWA now ONLY serves static files (much simpler)
+- API container directly exposed through Traefik
+- Both services use Let's Encrypt certificates
+- WebSocket timeout handled by Traefik (default 90s, configurable)