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

docker network create traefik-network

Set in .env.prod:

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

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:

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

Confirm api / web containers are healthy: docker compose ps
Verify both services attach to traefik-network
Check label traefik.docker.network matches the external network name

Certificate errors

Ensure ports 80 and 443 are reachable from the internet for HTTP-01 challenge
Confirm ACME_EMAIL is valid
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.

3.1 KiB Raw Permalink Blame History