Network Configuration Reference

This document serves as the single source of truth for all port and networking configuration.

Service Ports

Service	Port	Environment Variable	Config File
API	3001	PORT in apps/api/.env	apps/api/src/main.ts
Web	5173	WEB_PORT in root .env (optional)	apps/web/vite.config.ts
Docs	3002	n/a	docs/package.json
Database	5432	DATABASE_URL	PostgreSQL default
Redis	6379	REDIS_PORT	Bull queue

Configuration Files to Update

When changing ports, update these files:

API Port (3001)

1. apps/api/.env → PORT=3001
2. apps/api/.env.example → PORT=3001
3. apps/api/src/main.ts → process.env.PORT ?? 3001
4. apps/web/vite.config.ts → API_PORT constant
5. README.md → Documentation

Web Port (5173)

1. apps/web/vite.config.ts → WEB_PORT constant
2. README.md → Documentation

Docs Port (3002)

1. docs/package.json → "start": "docusaurus start --port 3002"
2. README.md → Documentation

OAuth Callback URLs

OAuth providers need to know the exact callback URLs:

Discord OAuth

# Callback URL in Discord Developer Portal
http://localhost:3001/api/v1/auth/discord/callback

Battle.net OAuth

# Callback URL in Battle.net Developer Portal
http://localhost:3001/api/v1/auth/battlenet/callback

⚠️ Important: If you change the API port, update these URLs in:

• Discord Developer Portal
• Battle.net Developer Portal
• apps/api/.env → DISCORD_CALLBACK_URL and BATTLENET_CALLBACK_URL

CORS Configuration

The API allows requests from the frontend:

// apps/api/src/main.ts
app.enableCors({
  origin: process.env.FRONTEND_URL || 'http://localhost:5173',
  credentials: true,
});

Update FRONTEND_URL in apps/api/.env if web port changes.

Proxy Configuration

The frontend proxies API requests:

// apps/web/vite.config.ts
proxy: {
  '/api': {
    target: `http://localhost:${API_PORT}`,
    changeOrigin: true,
  },
}

This means:

• http://localhost:5173/api/v1/health → proxies to → http://localhost:3001/api/v1/health

Running All Services

# Terminal 1 - API on :3001
pnpm api

# Terminal 2 - Web on :5173
pnpm web

# Terminal 3 - Docs on :3002
pnpm docs

Port Conflicts

If you see "EADDRINUSE" errors:

# Find process using a port
lsof -i:3001

# Kill process on a port
lsof -ti:3001 | xargs kill -9

Future: Environment Variables

Recommended improvement: Use environment variables everywhere:

# Root .env
API_PORT=3001
WEB_PORT=5173
DOCS_PORT=3002

Then reference process.env.API_PORT in all config files. This requires:

• Setting up dotenv loading in Vite config
• Updating NestJS to read from env
• Updating Docusaurus start script

Checklist: Changing a Port

• Update environment files (.env, .env.example)
• Update config files (main.ts, vite.config.ts, package.json)
• Update CORS origins if needed
• Update OAuth callback URLs in provider portals
• Update this document
• Update README.md
• Test all services start without conflicts
• Commit all changes together