HexaHost-GameCloud/docs/operations/server-migration.md

Server and host migration

Moving HexaHost GameCloud workloads between hosts: control plane relocation, game node replacement, and WHMCS host migration.

Control plane migration

Move from cp-01-old to cp-01-new:

1. Prepare new host — ansible-playbook -i inventories/production deploy/ansible/control-plane.yml
2. Stop writes on old host — docker compose stop api worker
3. Backup — PostgreSQL dump, Redis RDB, MinIO mirror, /opt/hexahost-gamecloud/.env.prod, Traefik acme.json
4. Transfer — Secure copy to new host (rsync over SSH, encrypted archive)
5. Restore — Follow backup-restore on new host
6. Update DNS — panel.example.net and api.example.net A/AAAA records to new IP
7. Start stack — docker compose -f deploy/compose/compose.prod.yml up -d
8. Verify — Health checks, WHMCS addon dashboard, node WebSocket reconnections
9. Decommission old host — Secure wipe after 72h parallel run (optional)

WHMCS requires no URL change if hostnames are unchanged. Update GameCloud API URL in addon settings only if api.example.net changes.

Game node migration

Replace node-01 with node-02 while preserving customer servers:

Add replacement node first

1. Create GameNode in admin API
2. Deploy agent: deploy/ansible/game-node.yml
3. Confirm ONLINE status

Drain old node

Follow node-drain. Running servers must stop and start on the new node.

Data considerations

• World data lives in Docker volumes on the node — not automatically migrated
• Customers should create a backup before migration window
• Admin can trigger backup via API, then restore after server starts on new node

DNS

Join hostnames point to the edge gateway, not individual nodes. No DNS change required for node migration unless edge IP changes.

Edge gateway migration

If EDGE_PUBLIC_HOST changes:

1. Update RFC2136 records or manual DNS for *.play.example.net
2. Deploy edge gateway on new IP
3. Worker DNS sync reconciles server_dns_records within 60s

WHMCS host migration

1. Export WHMCS database and mod_hexagamecloud_* tables
2. Copy integrations/whmcs/modules/ to new WHMCS install
3. Reconfigure addon: Integration ID, API Secret (unchanged on GameCloud side)
4. Run reconciliation dry-run: Addons → HexaHost GameCloud → Reconciliation
5. Re-register mTLS fingerprint if client certificate changes

See WHMCS installation.

MinIO / S3 migration

mc mirror old/gamecloud new/gamecloud

Update S3_ENDPOINT and credentials in .env.prod, restart API and worker.

Rollback

Keep old host powered but isolated for 72 hours. Rollback = revert DNS + restart old compose stack from pre-migration backup.

Related

• Backup and restore
• Disaster recovery
• Node drain