echoes-of-the-ash/old/API_SUBDOMAIN_MIGRATION.md

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

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