Skip to main content

Upgrade

An upgrade replaces the images and the release files, migrates the database to the new schema, and, when the release changes the face template model, migrates the stored templates. run.sh performs the database migration for you; the template migration is a separate step. Plan a maintenance window: the engine services are stopped during the migration.

Before you start​

  • Read the release notes of every version between yours and the target. They list manual steps, for example a changed template model or a watchlist update-log stream that must be regenerated.
  • Take a backup of the database and the S3 storage. Database migrations are forward-only; the backup is your rollback.
  • Record your local changes: keep a copy of your .env, .env.station and Compose files, or keep the production directory under your own version control, so you can compare them with the new release.
  • Make sure the new image versions are available in the registry your .env REGISTRY points to. If you mirror images into a private registry, mirror the new release first.

Steps​

  1. Get the new release package. Unpack it over the deployment directory so that docker-compose.yml, dependencies/, run.sh, deployment-common.sh and .env are replaced. docker-compose.override.yml, .env.station, secrets/ and branding/ are not part of the package and stay as they are.
  2. Re-apply your changes to the replaced files: credentials and hostnames in .env, CameraServicesCount, extra camera containers, and any edits you made in docker-compose.yml or dependencies/docker-compose.yml. The new .env already carries the new VERSION and STATION_VERSION. Changes kept in docker-compose.override.yml need no action.
  3. Run ./start.sh. It pulls the new images, migrates the database and starts the services.
  4. Check docker compose ps. If matcher, extractor, the face search service or the camera containers stop with a template compatibility error in their logs, the template model changed: run the template migration and then ./start.sh again.
  5. If the release notes say the watchlist update-log stream must be regenerated, run ./populate-wl-update-log-stream.sh. This matters on Leader sites and on sites with edge devices.
  6. Verify: open Station, check the version reported by the REST API, confirm camera previews, and run one identification.

Upgrading across several versions works the same way; the database migration covers the whole range, but apply the manual steps from each release's notes.

Keep production outside the git clone​

If you obtained Face Matcher from the GitHub repository, do not run production from the working copy. Copy the files into a dedicated directory such as /srv/face-matcher, keep your .env, licenses and overrides there, and use the clone only as the source of new release files. A git pull in a production directory would overwrite .env and leave the deployment with default credentials and hostnames.

Rollback​

Stop the services with ./stop.sh, restore the database and S3 backup taken before the upgrade, put back the previous release files and .env, and run ./start.sh. Do not try to run the old images against the migrated database.