# Control plane upgrades

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

## Version pinning

Set in `.env.prod`:

```env
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](backup-restore.md))
- [ ] WHMCS addon/server module compatibility verified
- [ ] Maintenance window communicated if API downtime expected
- [ ] Staging deploy completed successfully

## Standard rolling upgrade

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

```bash
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](../integrations/whmcs/upgrades.md). Upgrade GameCloud API before WHMCS server module when release notes specify API-first ordering.

## Post-upgrade verification

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

## Related

- [Control plane operations](control-plane.md)
- [Node drain](node-drain.md) — upgrade game nodes separately