Upgrade an existing installation

This page covers upgrades for a running Vittor environment. The upgrade replaces the delivered images while retaining business data and file resources. For a first deployment, see System deployment; for recovery after an incident, see Rollback after an incident.

Confirm before upgrading

1. Confirm the target release, package source, and checksum. Schedule a maintenance window and notify on-site users.
2. Inspect the current service state and record the current release, image digests, deployment parameters, terminal versions, and the latest successful recognition time.
3. Back up the database, personnel photos, and other file resources. Read the backup contents and confirm that the planned restore procedure works.
4. Confirm the target release's ports, environment parameters, and terminal compatibility. When existing data is reused, the database password must match the current environment.
5. Pause bulk enrollment, person changes, and device configuration changes during the upgrade so that old and new releases do not write business data at the same time.

Do not delete data volumes to “clean up” an upgrade issue. The pre-upgrade backup and service record are the basis for a rollback decision.

Perform the upgrade

1. Copy the target release package to the host and enter its directory. Do not overwrite or delete existing data volumes.

2. Set parameters for the current environment, at minimum the database password, Web port, and central host address:

   cd /path/to/new-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}"

3. Load the new images and start the services:

   bash deploy/load-and-start.sh

   When the images were loaded separately, run bash deploy/start.sh. The script recreates containers while retaining business data and file resources.

4. Inspect service status and logs. Confirm database health and that services are not repeatedly restarting:

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

5. Resume enrollment, person changes, and device configuration only after acceptance passes.

Acceptance after the upgrade

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 a known organization, space, and person	Data, photos, and file resources are readable
Discovery	GET /api/discovery/nodes	Enrollment and display addresses are reachable
Terminal configuration	Check System Configuration and terminal settings	The central address remains configured and terminals reconnect
Synchronization	Update one test person	The central record, target device, and result agree
Recognition loop	Perform one real test recognition	Receiver and display show the same person, device, and time

If a problem appears during the upgrade, preserve logs and the current state instead of repeatedly loading different releases. When the issue is tied to the release change, follow Rollback after an incident.

Upgrade precautions

• An upgrade replaces images and containers; it does not rerun initialization against existing data volumes.
• 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 mismatched environment parameters.
• Keep the upgrade record, backups, and logs in the site handover archive. Redact screenshots and issue reports.