Control plane upgrades

Rolling upgrades for HexaHost GameCloud API, worker, web, and infrastructure containers on the control plane.

Version pinning

Set in .env.prod:

GAMECLOUD_IMAGE_TAG=1.2.0

Build and tag images in CI, or pull from your registry. Never deploy :latest in production without a rollback plan.

Pre-upgrade checklist

Read release notes and migration requirements (docs/IMPLEMENTATION_STATUS.md)
Fresh PostgreSQL backup (backup-restore)
WHMCS addon/server module compatibility verified
Maintenance window communicated if API downtime expected
Staging deploy completed successfully

Standard rolling upgrade

cd /opt/hexahost-gamecloud

# Pull/build new images
export GAMECLOUD_IMAGE_TAG=1.2.0
docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod pull
docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod build

# Run database migrations (if applicable — via API container one-shot)
docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod run --rm api \
  pnpm --filter @hexahost/api prisma migrate deploy

# Recreate app containers one at a time
docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod up -d --no-deps worker
docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod up -d --no-deps api
docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod up -d --no-deps web

Infrastructure upgrades

Service	Notes
PostgreSQL	Major version requires `pg_upgrade` or dump/restore — plan maintenance window
Redis	Minor upgrades usually safe; snapshot before upgrade
MinIO	Follow MinIO release notes; backup volume first
Traefik	Test dynamic config with `traefik validate` equivalent (dry-run container)

Zero-downtime considerations

Run at least two API instances behind Traefik for true zero-downtime (single-node compose has brief API restart)
Worker: only one active consumer per-correct for some jobs; use graceful shutdown (SIGTERM) before replace
Web: Next.js standalone reload causes short 502; upgrade during low traffic

Rollback

export GAMECLOUD_IMAGE_TAG=1.1.0
docker compose -f deploy/compose/compose.prod.yml --env-file .env.prod up -d api worker web

If migrations ran forward-only, restore PostgreSQL from pre-upgrade dump.

WHMCS module upgrades

See WHMCS upgrades. Upgrade GameCloud API before WHMCS server module when release notes specify API-first ordering.

Post-upgrade verification

curl -sf https://api.example.net/api/v1/health/live
curl -sf https://panel.example.net/de

Admin panel login
WHMCS test suspend/unsuspend on staging service
Worker queue depth normal
Node heartbeats within 30s

Control plane operations
Node drain — upgrade game nodes separately

2.9 KiB Raw Blame History