Operations

A Face Matcher deployment is a directory with two Compose projects (face-matcher for the engine services and Station, face-matcher-dependencies for PostgreSQL, RabbitMQ and SeaweedFS), a handful of scripts and the .env files. All commands on this page run from that directory. The package contents are listed in Release package.

Scripts

Script	What it does
start.sh	Checks secrets/iengine.lic, sets STATION_PUBLIC_HOST (the address browsers use for image links; defaults to the host name) and calls run.sh. Prints the Station and API URLs.
run.sh	The release package's own start script: creates face-matcher-network, starts the dependencies, stops the engine services, migrates the database to the current version, creates the S3 bucket and starts all services with docker compose up -d.
stop.sh	Stops both projects. Data stays in the pgsqldata and seaweedfsdata volumes.
factory-reset.sh	Stops both projects and deletes containers, images and volumes, that is, all data. The license in secrets/ is kept.
migrate-faces.sh, finalize-non-migrated-faces.sh	Face template migration; see Template migration.
populate-wl-update-log-stream.sh	Rebuilds the watchlist update-log stream from the database; see Leader and Follower setup.

start.sh is safe to run again at any time, but it restarts every engine service. Use it after changes that need the database migration (a new CameraServicesCount, an upgrade); for everything else use the Compose commands below.

Configuration files

File	Configures
.env	Everything for the engine services: section 1 registry and image version, CameraServicesCount; section 2 shared settings (database, RabbitMQ, MQTT, S3, hosting, health checks, logging, telemetry, GPU, threading, notifications); section 3 per-service settings; section 4 Station version and port. Documented inline.
.env.station	Station: API and GraphQL addresses, camera preview hosts, S3 access, score-to-percentage conversion, authentication, custom member fields.
docker-compose.yml	The engine services as shipped in the release package.
docker-compose.override.yml	Station, restart: unless-stopped and user: root on the engine services. Keep your own additions (replicas, GPU, log rotation, extra cameras' policies) here: the file is not part of the release package, so it survives an upgrade.
dependencies/docker-compose.yml	PostgreSQL, RabbitMQ, SeaweedFS and pgAdmin, with their credentials and published ports.
secrets/iengine.lic	The license for this host. start.sh links it to ./iengine.lic, where the Compose files mount it.
branding/station/	Station logo, favicon and product naming.

Everyday commands

docker compose ps                                      # state of the engine services and Station
docker compose -f dependencies/docker-compose.yml ps   # state of the dependencies
docker compose logs -f api                             # follow one service's logs
docker compose restart extractor                       # restart one service (same configuration)
docker compose stop cam-3                              # stop one camera container
docker compose start cam-3

Every service should show Up (or running). A service that restarts in a loop usually reports the reason in its first log lines: a missing or wrong license, an unreachable dependency, or incompatible face templates after an upgrade.

Apply configuration changes

• After editing .env, run docker compose up -d. Compose recreates only the services whose configuration changed. docker compose restart does not re-read .env.
• To apply to one service only: docker compose up -d extractor.
• After editing .env.station: docker compose up -d station.
• After removing services from a Compose file: docker compose up -d --remove-orphans.
• When a change does not seem to take effect: docker compose up -d --force-recreate.
• After editing dependencies/docker-compose.yml: docker compose -f dependencies/docker-compose.yml up -d.

Before production

Change the default credentials of PostgreSQL, RabbitMQ, S3 and pgAdmin in dependencies/docker-compose.yml, .env and .env.station; restrict the published ports (see Network and ports); set up log rotation and backups.