Document verified manual Servatrice 3.1.2 upgrade and rollback

This commit is contained in:
Dandaedre 2026-11-10 12:45:23 +01:00
parent 4acb8c105f
commit 9a648e2507
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
3 changed files with 96 additions and 21 deletions

View File

@ -549,7 +549,7 @@ status. Non-`.cod` files are ignored during directory scans.
[config/servatrice/README.md](config/servatrice/README.md) records sanitized snapshots
of the local Servatrice configuration, the private backup location, and the
assessment of upgrading to 3.1.2. These files are for manual safekeeping only and
completed manual upgrade to 3.1.2, validation, and rollback instructions. These files are for manual safekeeping only and
are excluded from token publication and installation. No Servatrice deployment
or database migration runs in CI.

View File

@ -53,7 +53,10 @@ executable was found in PATH. Podman contains these existing, stopped containers
The original Linux Compose file publishes only port 4748 (WebSocket), although
Servatrice also configures TCP port 4747. This snapshot preserves that choice.
The MySQL image is unpinned and the data volume is anonymous; do not recreate or
upgrade it blindly. No containers, ports, or database mounts were changed.
upgrade it blindly. These original containers and their database volume are retained and stopped
after the manual upgrade below. Their restart policies were changed to `no` to
prevent conflicts with the upgraded server; their original policies are saved
in the private container metadata backup.
## Update assessment and isolated check
@ -71,22 +74,89 @@ version command; it does not prove compatibility with the configured database.
The downloaded image ID is
`f38a4c5cdfa6721e44e9a784290be6b8c3ed9e80131536f5066ee1f365566093`.
**The installed server was not switched to the new image.** The original source's
bootstrap schema is version 34, whereas 3.1.2 expects version 40. The actual stored
database version was not queried because MySQL remains stopped. Updating just
the image cannot be assumed safe. No SQL migrations were applied.
## Completed manual upgrade — 2026-11-10
A future manual upgrade should:
Following explicit authorization, the server was switched to **Servatrice 3.1.2**.
The source checkout and original INI remain unchanged. The active server mounts
`servatrice/docker/servatrice-docker.ini` read-only; its bytes were checked against
the private backup. No credentials were changed or added to Git.
1. Back up the stopped MySQL volume and prove that the backup can be restored.
Also retain the original database image, server image, and private config backup.
2. Start an isolated clone using the same MySQL image, inspect its actual schema
version and SQL mode, and rehearse the corresponding upstream migrations up
to schema 40. Bootstrap `servatrice.sql` is not a migration for existing data.
3. Test the new server against that cloned database with copied private settings
and no public ports. Verify authentication, rooms, registration, and replays.
4. Only after validation, plan a manual cutover with rollback of both database
and server image. Reverting the server image alone does not revert a schema.
The stopped original MySQL volume was exported, checksummed, and restored into a
separate named volume. The restored database reported schema 34 and no registered
accounts. All six upstream migrations (34 → 40) succeeded on that clone. Existing
data was retained; no database reset was necessary. MySQL uses the same image ID
as before, avoiding a simultaneous database engine upgrade.
This repository intentionally provides no automatic Servatrice deployment or
migration task. The downloaded candidate is available for that future rehearsal.
Active rootless Podman resources:
| Resource | Name / setting |
| --- | --- |
| Server | `cockatrice_servatrice_312` |
| Database | `cockatrice_mysql_312` |
| Database volume | `cockatrice_mysql_312_20261110-123909` |
| Private container network | `cockatrice_upgrade_20261110-123909` |
| Host publication | `0.0.0.0:4748` → WebSocket port 4748 |
| Server image | Official 3.1.2 image ID recorded above |
| MySQL image ID | `b0648a94df9f763bcb89445f29de8f7398a03f50a7bc6e9f1da18f1d3812d1d1` |
Both new containers have restart policy `always`. Host reboot startup was not
changed or tested. TCP 4747 remains unpublished, matching the original deployment.
MySQL has no published port; the new container network is internal.
The server was first tested on loopback port 14748, then on its normal port 4748.
Protocol checks passed for the server identity/version, guest login, registration,
password login, and the configured room listing. The temporary registered account
was deleted afterward. Full games, replay round trips, SMTP, remote access through
any proxy/firewall, and reboot behavior were not tested.
### Private backups
```text
/home/dandaedre/.local/share/servatrice-backups/upgrade-20261110-123909/
```
This private directory contains the original configs and container metadata,
`mysql-volume.tar` (cold schema-34 database backup) and its verified SHA-256,
`schema40.sql` (post-upgrade logical database backup), a pre-cutover logical dump,
the upstream migration SQL, runtime state, and validation notes. The archive was
actually restored and started successfully. Treat all backups as secret-bearing;
keep them outside Git and copy them separately for protection against disk loss.
The original containers, original volume, and tagged rollback images also remain
available locally. Do not prune those resources while rollback is needed.
### Manual operation and rollback
Use the new container names for normal operation:
```sh
podman logs --tail 100 cockatrice_servatrice_312
podman start cockatrice_mysql_312
# Wait for MySQL to report ready before starting the server.
podman start cockatrice_servatrice_312
```
Do not use the checkout's old Compose file to operate the upgraded deployment:
it still describes the old containers. This upgrade uses persistent Podman
containers, not a new Compose deployment or CI job.
To roll back, first stop the new pair, then start the retained original pair:
```sh
podman stop cockatrice_servatrice_312
podman stop cockatrice_mysql_312
podman start cockatrice_mysql_1
# Check database readiness before continuing:
podman exec cockatrice_mysql_1 sh -c 'export MYSQL_PWD="$MYSQL_ROOT_PASSWORD"; mysqladmin -uroot ping'
podman start cockatrice_servatrice_1
# Once rollback is confirmed, move the restart policy back to the old pair:
podman update --restart=no cockatrice_servatrice_312
podman update --restart=no cockatrice_mysql_312
podman update --restart=always cockatrice_mysql_1
podman update --restart=always cockatrice_servatrice_1
```
Rollback returns to the original schema-34 data: writes made after the upgrade
will not appear there. Back up the active database before reverting if those
writes matter. Never point the old server at the migrated schema-40 volume.
This repository provides no automatic Servatrice deployment or migration task.

View File

@ -26,9 +26,14 @@
"candidate_commit": "bbc7e462ff0e9fd5391a0626e6f46fc79223aad5",
"source_schema_file_version": 34,
"candidate_required_schema_version": 40,
"actual_database_schema_version": "not queried; database container remains stopped",
"deployment": "none; original files, stopped containers and database volume unchanged",
"actual_database_schema_version": 40,
"deployment": "manual upgrade completed; new containers use migrated clone, original containers stopped and original volume retained",
"candidate_image": "ghcr.io/cockatrice/servatrice:2026-10-25-release-3.1.2",
"candidate_image_id": "f38a4c5cdfa6721e44e9a784290be6b8c3ed9e80131536f5066ee1f365566093",
"candidate_check": "--version passed in network-isolated read-only temporary container without mounts; existing deployment not upgraded"
"candidate_check": "3.1.2 live: guest login, registration, password login, configured room listing passed",
"upgrade_backup": "/home/dandaedre/.local/share/servatrice-backups/upgrade-20261110-123909",
"pre_upgrade_database_schema_version": 34,
"active_server_container": "cockatrice_servatrice_312",
"active_database_container": "cockatrice_mysql_312",
"active_database_volume": "cockatrice_mysql_312_20261110-123909"
}