cockatrice-custom-tokens/config/servatrice
Dandaedre 9a648e2507
Document verified manual Servatrice 3.1.2 upgrade and rollback
2026-11-10 12:45:23 +01:00
..
snapshots Preserve sanitized Servatrice configs and document safe upgrade assessment 2026-11-10 12:32:52 +01:00
README.md Document verified manual Servatrice 3.1.2 upgrade and rollback 2026-11-10 12:45:23 +01:00
UPSTREAM-LICENSE Preserve sanitized Servatrice configs and document safe upgrade assessment 2026-11-10 12:32:52 +01:00
snapshot.json Document verified manual Servatrice 3.1.2 upgrade and rollback 2026-11-10 12:45:23 +01:00

README.md

Servatrice configuration safekeeping

These are manual snapshots of the configured Servatrice checkout at /home/dandaedre/Documents/Git/Cockatrice/servatrice, captured on 2026-11-10. They are not deployment configuration for this repository: Jenkins, the token installer, and the mock deploy scripts do not apply or publish them.

Saved files

Snapshot Original Purpose
snapshots/standalone.ini servatrice/servatrice.ini Password authentication, no database; server and room customizations.
snapshots/container.ini servatrice/docker/servatrice-docker.ini SQL authentication and registration, MySQL host mysql; configured container server.
snapshots/modified-example.ini servatrice/servatrice.ini.example Locally modified example, retained for comparison.
snapshots/docker-compose.yml docker-compose.yml Original Linux container topology, with credentials removed.
snapshots/docker-compose.yml.windows docker-compose.yml.windows Original Windows variant for reference.
snapshots/Dockerfile Dockerfile Original source-build container recipe.

The INI password fields contain __RESTORE_<SECTION>_PASSWORD__ markers. These are literal placeholders, not environment expansion understood by Servatrice. The Compose files require private MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD values. Do not run the snapshots without restoring the appropriate credentials and reviewing paths. Original $PWD and relative mounts refer to a complete Cockatrice source checkout, not this snapshot directory. The Dockerfile likewise requires that upstream source tree as its build context.

Exact original copies, including credentials and the original bootstrap SQL, were saved and hash-verified outside Git at:

/home/dandaedre/.local/share/servatrice-backups/20261110-123010/

That directory has mode 0700, and its files have mode 0600. Keep it private; it is not uploaded or included in this repository. It is a configuration backup, not a backup of the existing database. Preserve it separately if moving machines. snapshot.json records the original source revision and the reviewed release. Upstream files retain their upstream license; see UPSTREAM-LICENSE.

Runtime found during inspection

The local checkout reports 2026-01-28-Development-2.11.0-beta.48 and has local modifications, so it was not reset, pulled over, or replaced. No host servatrice executable was found in PATH. Podman contains these existing, stopped containers:

  • cockatrice_servatrice_1, image localhost/servatrice:latest, using the original servatrice/docker/servatrice-docker.ini at /tmp/servatrice.ini.
  • cockatrice_mysql_1, image docker.io/library/mysql:latest. Its actual data is in the anonymous volume 8df9615530dd486623c08f81e074247712ea6497f5521f6ff10f8024c7e39597, mounted at /var/lib/mysql. The local servatrice/mysql-storage/ folder is not its data.

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. 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

The GitHub releases API identified 2026-10-25-Release-3.1.2 as the latest stable release at inspection time. Its source commit is bbc7e462ff0e9fd5391a0626e6f46fc79223aad5.

The official image ghcr.io/cockatrice/servatrice:2026-10-25-release-3.1.2 was pulled alongside the old image. It reported Servatrice 3.1.2 (2026-10-31) with --version in a temporary container with networking disabled, a read-only root, all capabilities dropped, and no configuration or database mounts. The test container was removed automatically. This proves the executable starts for its version command; it does not prove compatibility with the configured database. The downloaded image ID is f38a4c5cdfa6721e44e9a784290be6b8c3ed9e80131536f5066ee1f365566093.

Completed manual upgrade — 2026-11-10

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.

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.

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

/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:

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:

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.