Rollback after an incident

Use this page when the current release is confirmed to affect business operations and the site must return to the previous delivered state. Preserve evidence and backups first. For a diagnosable network or configuration issue, start with Troubleshooting. For first deployment, see System deployment; for a routine upgrade, see Upgrade an existing installation.

When to roll back

Consider a rollback when troubleshooting cannot restore the site within the maintenance window and one of these conditions applies:

• Core services repeatedly restart or fail the health check.
• Login or known-data queries became unavailable after the release change.
• Person synchronization or the recognition loop worked before the upgrade and keeps failing afterward.
• The target release has a confirmed compatibility problem with the site's devices or terminals.

A rollback restores a release; it does not automatically restore historical data. Decide separately whether the database or file resources must be restored.

Preserve information first

1. Record the incident time, current release, deployment parameters, service state, and terminal versions.
2. Save upgrade logs, browser errors, and one reproducible business record. Redact screenshots and logs first.
3. Confirm the previous image package, its matching configuration, and readable database and file-resource backups.
4. Pause enrollment, person changes, and device configuration changes so the rollback does not create new differences.
5. Name the rollback owner and acceptance owner, and confirm host and on-site terminal access during the window.

Perform the release rollback

1. Enter the previous package directory and set the database password, Web port, and central host address from that release's handover record:

   cd /path/to/previous-deployment-package
   export MYSQL_ROOT_PASSWORD='provide this through a controlled method'
   export DISCOVERY_HOST='192.168.1.20'
   export DISCOVERY_HTTP_BASE_URL="http://${DISCOVERY_HOST}:${WEB_PORT:-80}"

2. Load the previous images and start the services:

   bash deploy/load-and-start.sh

   When the images are already loaded, run bash deploy/start.sh. These operations recreate containers but must not delete existing data volumes.

3. Inspect status and logs:

   bash deploy/status.sh
   docker compose logs --tail=100 server web mysql

4. Complete the acceptance checklist below. Do not resume bulk site operations until the business flow is restored.

Acceptance after rollback

Layer	Check	Passing result
Services	docker compose ps and logs	All three services are stable and the database is healthy
Web	Sign in to the management site	The page, account, and permissions work
Data	Query data known before the upgrade	Data and file resources match the rollback target
Discovery	GET /api/discovery/nodes	Enrollment and display nodes are discoverable
Synchronization	Check one test person	The target device and processing result are healthy
Recognition loop	Perform one real test recognition	Receiver and display show the same person, device, and time

Decide whether to restore data

• When only images or runtime logic are affected, keep the current data volumes and roll back the images first.
• If data is damaged, incorrectly written, or incompatible with the target release, evaluate a database or file-resource restore.
• Before restoring data, back up the current incident state, confirm the backup point and restore scope, and record the approval.
• After a restore, repeat login, query, synchronization, and recognition acceptance. Never import an unverified historical dump into production.

Rollback precautions

• Never use docker compose down -v) or manually delete vittor_mysql_data, vittor_runtime, or vittor_resource`.
• Do not mix old images, a new Compose file, and new environment parameters.
• If no matching previous package or readable backup exists, pause the rollback and contact the delivery owner.
• Keep incident logs, release information, acceptance results, and unresolved items for follow-up repair.