97 lines
3.1 KiB
Markdown
97 lines
3.1 KiB
Markdown
# 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)
|