headquarter/openspec/changes/archive/2025-05-17-oauth-traefik-integration/proposal.md

Why

The current setup hardcodes Authentik URLs in the API config and provides only a basic docker-compose.yml without reverse proxy support. For production deployment, the platform needs to integrate with an existing Traefik reverse proxy and have all external service URLs fully configurable via environment variables.

What Changes

• Externalize all Authentik and domain configuration to environment variables (no more hardcoded URLs in config.py).
• Add docker-compose.traefik.yml for deployment behind an existing Traefik instance with all domain names as env vars.
• Update .env.example to document all new environment variables for both development and traefik modes.
• Add proxy web name configuration for the frontend to know its public URL.
• Verify OAuth callback URLs work correctly with configurable domains.

Capabilities

New Capabilities

• traefik-deployment: Docker Compose setup for deploying behind an existing Traefik reverse proxy with environment-based domain configuration.

Modified Capabilities

• docker-infrastructure: Add traefik deployment mode and externalize all domain/service URLs.
• auth-oauth: Make Authentik URLs and callback URLs fully environment-configurable instead of hardcoded.

Impact

• apps/api/src/config.py: Remove hardcoded Authentik URLs, read from environment.
• apps/api/src/api/auth.py: Use configurable redirect/callback URLs.
• .env.example: Add all new environment variables.
• docker-compose.traefik.yml: New file for traefik deployment.
• Frontend may need VITE_APP_URL or similar for OAuth redirect.