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