Face Matcher Server
Face Matcher is a set of cooperating containers started by one Docker Compose project (face-matcher) on a single Docker network (face-matcher-network). From a high-level view it has two parts: the dependencies (third-party infrastructure that stores data and carries messages) and the engine services (Innovatrics containers that decode video, detect and extract faces, match them against watchlists and publish results). Station, the web UI, runs as one more container next to the engine services.
Every engine service is stateless with respect to its own container: all durable data lives in the dependencies. That is what makes it possible to restart, replace or scale individual services without touching the rest of the deployment.
Dependencies
| Service | Role | In-network address | Notes |
|---|---|---|---|
| PostgreSQL 14 | Relational database | pgsql:5432 | Watchlists, watchlist members, biometric templates, cameras, detections, match results and configuration. |
| RabbitMQ 4.3 | Message broker | rmq:5672 (AMQP), rmq:1883 (MQTT), rmq:5552 (streams) | Intra-service communication, notification delivery, the MQTT endpoint for edge devices and the watchlist update-log stream used by synchronization. Management UI on host port 15672. |
| SeaweedFS | S3-compatible object storage | seaweedfs:8333, bucket face-matcher | Images: enrollment pictures, face and pedestrian crops, full frames. |
| pgAdmin | Database administration | host port 7070 | Optional convenience tool, not used by the engine services. |
Not every feature needs both stores. Structured data and templates always go to PostgreSQL; image storage in S3 can be switched off entirely for privacy-sensitive deployments (see Data retention). A direct liveness check through the REST API does not touch either store.
All dependencies ship with development credentials (RabbitMQ guest/guest, S3 admin/admin). Change them before production use.
Engine services
The table lists the container names from the release package. Services marked Yes in the Scalable column can run as several replicas to handle more load; see Deployment topologies and the Scaling guide.
| Container | Scalable | Responsibility |
|---|---|---|
base | No | Housekeeping features that need no service of their own: database cleanup, tracklet recovery, general background jobs. |
api | Yes | REST API (host port 8098, in-network api:8080). |
graphql-api | Yes | GraphQL API with subscriptions (host port 8097, in-network graphql-api:8080). |
cam-1 … cam-5 | Yes (one per camera) | Server-side processing of one RTSP stream each: decoding, in-process or remote detection, tracking, preview. See Server-side RTSP processing. |
cam-nx | — | An additional camera slot with a fixed service identifier and no published preview port. |
detector | Yes | Dedicated face detection on CPU or GPU, used by cameras configured for remote detection. |
extractor | Yes | Generates biometric templates and extracts age, gender and face-mask attributes. |
matcher | Yes | Matches extracted templates against watchlist members (the watchlist matcher). |
face-matcher | Yes | The face search service: searches a template against all faces detected in the past, not against watchlists. See Face search. |
liveness | Yes | Passive liveness (spoof check) on CPU or GPU. |
pedestrian-detector | Yes | Detects pedestrians in incoming frames. |
pedestrian-extractor | Yes | Extracts attributes of detected pedestrians. |
object-detector | Yes | Detects common objects (vehicles, animals, bags and similar). |
streamdatadbworker | Yes | Writes face, pedestrian and object tracklets produced by the cameras into the database and S3. |
edge-stream-processor | No | Consumes FrameData messages from edge devices; one service serves all edge streams. See Edge streams. |
edge-streams-state-synchronizer | No | Synchronizes watchlist members to edge devices over MQTT. |
db-synchronization-leader | No | Publishes watchlist changes to Follower sites over gRPC (host port 8100). |
db-synchronization-follower | No | Pulls watchlist changes from a Leader site into the local database. |
Station runs as the fm-station container (host port 8000) and talks to the REST and GraphQL APIs like any other client.
Because the container face-matcher shares its name with the product, this documentation always calls it the face search service in prose.
Deployment and scalability
Face Matcher scales vertically (more and faster CPU cores, optionally a GPU) and horizontally (more replicas of the scalable services, spread across servers that share the same dependencies). The smallest useful deployment is a single server running everything; the largest is several geographically separated sites whose watchlists are kept in sync by the Leader and Follower services. The options are compared in Deployment topologies; the host ports and in-network addresses are listed in Network and ports.