# 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](backup-restore.md) 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](node-drain.md). 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](../integrations/whmcs/installation.md).

## MinIO / S3 migration

```bash
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](backup-restore.md)
- [Disaster recovery](disaster-recovery.md)
- [Node drain](node-drain.md)