Upgrade and backup

Back up first, upgrade Panel and Daemon, then check your game servers and plugins.

Before upgrading to 1.2.0

• Panel, Daemon, Registry, Client, and Wiki use 1.2.0. Upgrade Panel and Daemon together with the same generated contract manifest. Official plugins, the plugins workspace, and @gamex/plugin-tools remain at 1.0.0.
• Update installed components separately. Client 1.2.0 uses Panel and Daemon 1.2.0 images by default; updating a server does not replace the desktop application or its private runtime.
• Back up before changing images or configuration, and review the file policy below.

File-size policy

FILE_UPLOAD_HARD_MAX_BYTES is the shared limit for asset uploads, Workspace uploads and imports, and downloads into a Workspace. Its default is 2147483648 bytes (2 GiB).

The old WORKSPACE_FILE_HARD_MAX_BYTES server setting and workspaceFiles.maxFileBytes platform setting no longer control this limit. Record their values and remove the obsolete server setting from configuration. Existing custom FILE_UPLOAD_HARD_MAX_BYTES values remain effective; stored Workspace limits are ignored rather than copied into it. If you relied on the former 1 GiB default or another smaller limit, set the shared value explicitly before restarting. Separate per-Workspace size limits are unavailable.

Browser downloads from a Workspace stream in chunks of at most 48 MiB; the upload limit is not a total browser-download limit. Allow at least 50 MiB per request at reverse proxies for multipart overhead and set timeouts for the complete transfer. See HTTPS.

Personal-memory migration from 1.0.0

The 1.1.0 migration preserves personal memories and rejects legacy shared or Workspace memory, generation jobs, and usage that cannot become personal data. Export and back up the records using the old version, then explicitly remove the records identified by the migration error before retrying. Migration does not delete them automatically.

Databases already migrated to 1.1.0 do not repeat this conversion when upgrading to 1.2.0. Check and apply any pending migrations with the target version; do not delete personal memories or rerun initial setup.

What to back up

Installation	Back up
Panel built from source	Repository-root config.toml and its rollback files, data, logs, and program version; use the actual configuration directory if GAMEX_CONFIG_DIR is set
Panel installed by the native installer	config, data, and logs under /var/lib/gamex-panel/, plus service configuration and program version
Native Daemon (Linux)	/etc/gamex-daemon/ and /var/lib/gamex-daemon/; keep configuration, identity, and command journal together
Native Daemon (macOS / Windows)	Use the node configuration paths to back up the configuration file, identity, and state directories together
Compose	The original configuration directory, project name, image versions or digests, and panel-data, panel-logs, daemon-data, and enrollment volumes used by the deployment; the Wiki template uses the gamex_ volume prefix

Paths shown are defaults. The Compose installer uses /opt/gamex-compose/ and records image digests in its configuration and manifest. Keep those files with the backup; custom deployments use their actual paths and volume names.

• Use the database's backup tools for external databases and include external object storage when configured.
• Back up workspace files and Docker workspace volumes on each game host separately. These are not inside the Compose application's named volumes.
• Preserve encryption keys, identity material, file permissions, and plugin data. Back up private asset originals under Panel's data/assets with the database; external public object storage does not contain them. Plugin event bindings and delivery records are part of the Panel database.
• Restrict access to backups and verify restoration before relying on them.

Upgrade sequence

1. Read the target release notes and check Panel, Daemon, plugin, and database schema compatibility.
2. Stop affected game server writes or take a consistent snapshot, then stop Panel and affected node services.
3. Back up data, the previous programs or images, configuration, and the Compose project name.
4. Install the target program or image without replacing persistent data.
5. Apply the target Panel version's database migration before starting Panel.
6. Start services and verify login, node connectivity, workspace files, terminals, game servers, and plugin behavior.

The installation scripts do not perform version upgrades. Keep the same Compose project name and persistent volumes. Upgrade containerized Daemons by replacing their image; use daemon update only for a native Daemon installation.

Apply Panel database migrations

Use the target version to check migration status and apply pending updates. Before upgrading from 1.0.0, complete the personal-memory migration prerequisites. The commands below change the database, so complete your backup first. New installations are initialized in the browser and do not need this step again.

For a source installation, stop Panel and run from the target Panel repository using the same account, configuration directory, and database as the service:

npm --prefix backend run db:status &&
npm --prefix backend run db:migrate &&
npm --prefix backend run db:check

For a compiled installation, run the equivalent node dist/backend/scripts/database.js status, up, and check commands from the program root. Continue only after each succeeds, retaining the service's GAMEX_CONFIG_DIR and permissions.

For Compose, update compose.yaml to the target images, then run from the original configuration directory. These commands apply to this Wiki's default template. Keep database services running in custom projects; --no-deps does not start them:

docker compose stop panel &&
docker compose pull &&
docker compose run --rm --no-deps panel \
  node dist/backend/scripts/database.js status &&
docker compose run --rm --no-deps panel \
  node dist/backend/scripts/database.js up &&
docker compose run --rm --no-deps panel \
  node dist/backend/scripts/database.js check &&
docker compose up -d &&
docker compose ps

For the default installer deployment, replace each docker compose prefix with sudo docker --host unix:///var/run/docker.sock compose -p gamex -f /opt/gamex-compose/compose.yaml; use your actual project and file if customized. Installer images are pinned by digest, so changing a tag elsewhere does not update them. Select the target image or digest explicitly in the retained Compose file.

If schema validation or migration fails, keep the backup and diagnose the reported mismatch before starting services. Do not delete the database, reset node state, or rerun initial setup to bypass the error.

Restore and roll back

Stop services before restoring. Restore the matching configuration, encryption keys, Panel database, node identities and journals, and workspace data together. Run only one backend process per Panel database.

To return to the previous version, use the complete backup taken before upgrading and its matching programs or images. Replacing programs alone does not undo data changes. Records explicitly removed before the personal-memory migration require the earlier backup for recovery. Database rollback is also blocked by retained plugin event data, conversation integration contexts, or queued tasks without a login session; completed tasks alone do not establish that rollback is safe.

down -v, deleting data directories, or reinitializing databases erases persistent data.