Enhance API with OIDC support, including login and callback endpoints. Update environment variables for OIDC configuration in .env.example. Add new features to the catalog service for listing software families, Minecraft versions, and deployment regions. Implement server management actions such as kill, delete, and update in the servers module. Integrate feature flags for maintenance mode in server operations. Update pnpm-lock.yaml with new dependencies and versions.

docs/operations/traefik.md

@@ -0,0 +1,96 @@
+# Traefik operations
+
+HexaHost GameCloud exposes the customer panel (`web`) and REST API (`api`) through Traefik on the control plane host. Game nodes and the edge gateway are **not** routed through this stack.
+
+## Layout
+
+| Path | Purpose |
+|------|---------|
+| `deploy/traefik/traefik.yml` | Static config — entry points, ACME, providers |
+| `deploy/traefik/dynamic/gamecloud.yml` | Middleware, TLS options, optional file routers |
+| `deploy/compose/compose.prod.yml` | Docker labels for primary routing |
+
+## Prerequisites
+
+```bash
+docker network create traefik-network
+```
+
+Set in `.env.prod`:
+
+```env
+TRAEFIK_NETWORK=traefik-network
+WEB_HOST=panel.example.net
+API_HOST=api.example.net
+ACME_EMAIL=ops@example.net
+APP_URL=https://panel.example.net
+API_URL=https://api.example.net
+TRUSTED_PROXY_COUNT=1
+```
+
+## Run Traefik
+
+Example standalone container (adjust paths):
+
+```bash
+docker run -d \
+  --name traefik \
+  --restart always \
+  -p 80:80 -p 443:443 \
+  -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -v /opt/hexahost-gamecloud/deploy/traefik/traefik.yml:/etc/traefik/traefik.yml:ro \
+  -v /opt/hexahost-gamecloud/deploy/traefik/dynamic:/etc/traefik/dynamic:ro \
+  -v /opt/hexahost-gamecloud/letsencrypt:/letsencrypt \
+  --network traefik-network \
+  traefik:v3.2
+```
+
+Then start the application stack:
+
+```bash
+docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod up -d
+```
+
+## Routing
+
+| Host | Service | Health check |
+|------|---------|--------------|
+| `panel.example.net` | `web:3000` | `GET /de` |
+| `api.example.net` | `api:3001` | `GET /api/v1/health/live` |
+
+HTTP on port 80 redirects to HTTPS. API requests receive rate limiting (`100 req/s` average, burst `200`).
+
+## WHMCS integration mTLS
+
+WHMCS integration traffic uses the same `api.example.net` host. When `INTEGRATION_MTLS_ENABLED=true`, terminate client certificates at Traefik or nginx and forward `X-HGC-Client-Cert-Fingerprint`. See [WHMCS mTLS](../integrations/whmcs/mtls.md) and `deploy/nginx/integration-mtls.conf.example`.
+
+## Certificate renewal
+
+Let's Encrypt certificates are stored in `/letsencrypt/acme.json`. Back up this file before host migrations. Traefik renews automatically; monitor expiry via the Traefik dashboard or Prometheus metrics.
+
+## Troubleshooting
+
+### 502 Bad Gateway
+
+1. Confirm `api` / `web` containers are healthy: `docker compose ps`
+2. Verify both services attach to `traefik-network`
+3. Check label `traefik.docker.network` matches the external network name
+
+### Certificate errors
+
+1. Ensure ports 80 and 443 are reachable from the internet for HTTP-01 challenge
+2. Confirm `ACME_EMAIL` is valid
+3. Inspect Traefik logs: `docker logs traefik 2>&1 | jq .`
+
+### Wrong client IP in audit logs
+
+Increase `TRUSTED_PROXY_COUNT` on the API to match the number of reverse-proxy hops.
+
+## Ansible
+
+Control plane provisioning is described in `deploy/ansible/control-plane.yml`. After OS setup, copy Traefik and compose files to `/opt/hexahost-gamecloud` and enable systemd or compose restart policies.
+
+## Related
+
+- [Control plane operations](control-plane.md)
+- [Installation (development)](installation.md)