144 lines
4.0 KiB
Markdown
144 lines
4.0 KiB
Markdown
# 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)
|