87 lines
2.9 KiB
Markdown
87 lines
2.9 KiB
Markdown
# 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
|