Skip to main content

Deployment topologies

Face Matcher runs as one Docker Compose project, but the containers do not have to share a machine. Three topologies cover the range from a proof of concept to a multi-site estate. This page explains what each one is for and what it implies; the step-by-step procedures are in the guides linked from each section.

Single server​

All dependencies and all engine services run on one Linux host. This is what the release package does out of the box, and it is the right choice for evaluations and for production sites with a handful of cameras. Capacity is bounded by that host: add CPU cores or a GPU (vertical scaling) and add replicas of the scalable services or more camera slots until the machine is saturated. See Hardware requirements and the Scaling guide.

Multi-server site​

When one host is not enough, the same deployment is spread over several servers that form a single site: one set of dependencies (PostgreSQL, RabbitMQ, SeaweedFS), and engine services on as many servers as needed. Typical layouts:

  • Dependencies on their own server, engine services on the others. Storage I/O and message traffic stay off the processing hosts.
  • Cameras grouped by server: each processing server runs the camera services for its group of RTSP streams plus its own extractors and matchers, all pointing at the shared dependencies.

Every server runs the same Compose files; the only difference is that .env on the processing servers points RabbitMQ__Hostname, MQTT__Hostname, ConnectionStrings__CoreDbContext and S3Bucket__Endpoint at the dependency server instead of the local container names, and the dependency host opens the ports listed in Network and ports. A site has one database and therefore one set of watchlists, cameras and history. Procedure: Multi-server deployment.

Multi-site: Leader and Follower​

Sites at geographically separate locations (offices, terminals, branches) each run their own complete deployment and keep working independently, but share one centrally managed set of watchlists. One site is the Leader; all others are Followers.

Leader publishes watchlist changes over gRPC; Followers poll and apply them locally

What synchronizes. Every watchlist change on the Leader (registering, re-registering or removing members, assigning members to watchlists) is appended in order to a journal, the watchlist update-log stream in RabbitMQ. The db-synchronization-leader service exposes it over gRPC (host port 8100). Each Follower's db-synchronization-follower service polls that endpoint, reads the changes in batches and applies them to the local database in the same order, which gives eventual consistency even after long outages. Templates travel with the members, so Followers match locally without contacting the Leader.

What stays local. Only watchlists and members are synchronized. Cameras, detections, match results and images remain at the site that produced them and are never sent to the Leader.

Rules and limitations.

  • Watchlist management happens only on the Leader. Followers run with read-only watchlists (FeatureManagement__ReadOnlyWatchlists=true) and start with empty ones: any pre-existing watchlist data on a Follower is deleted on first sync.
  • Disable watchlist autolearn on Followers, because their matches are not fed back to the Leader.
  • The Leader may be single- or multi-tenant and may run on premises or in the cloud; each Follower is single-tenant.
  • A Follower keeps identifying while the link to the Leader is down and catches up when it returns.
  • Protect the gRPC endpoint: enable authentication on the Leader (Authentication__*, with ClientAuthentication__* on the Followers) and put TLS in front of it whenever the sites talk over a network you do not control.

Procedure: Leader and Follower setup. Synchronizing members to edge devices inside a site is a separate mechanism, see Edge watchlist sync.