Enhance API with OIDC support, including login and callback endpoints. Update environment variables for OIDC configuration in .env.example. Add new features to the catalog service for listing software families, Minecraft versions, and deployment regions. Implement server management actions such as kill, delete, and update in the servers module. Integrate feature flags for maintenance mode in server operations. Update pnpm-lock.yaml with new dependencies and versions.

2026-07-05 18:39:53 +02:00
parent bf36cb3159
commit 50cd4b3ffd
225 changed files with 17824 additions and 436 deletions
--- a/docs/operations/upgrades.md
+++ b/docs/operations/upgrades.md
@@ -0,0 +1,86 @@
+# 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