Planning reference: volumes and infrastructure figures in this document are hypothetical sizing scenarios, not measured product capacity or deployed installations. Validate workload, costs, security and recognition performance before procurement. The current feature overview is available at /features.
Fingerprint matching at national scale runs on dedicated matcher servers. Each one holds a share (a shard) of all fingerprint templates in memory and compares probes against it with native C++ matching, which scans more than 10 million templates in under 1 second on a 64-core server. The application servers send every search to all shards and merge the results.
This scatter-and-merge mode is built into Sentinel ID:
- an application server with
MATCH_NODESset works as the coordinator; - a matcher server is started with
SHARD_IDandSHARD_COUNTand loads only the templates of its shard; - new enrolments are sent to the server that owns them over the internal API (
/internal/fingerprints/add), protected byMATCH_NODE_KEY.
1. Build the native matcher (every matcher server)
The native C++ matcher is required at national scale; the build step below compiles it for the server's CPU.
sudo apt install -y build-essential cmake
cd /opt/sentinel
sudo -u sentinel npm ci --omit=dev
sudo -u sentinel npm run build:native
On start-up the log must report the native fingerprint engine. If the build is missing, the server falls back to a much slower reference matcher, so make your monitoring alert when the native engine is not reported: a fallback must never go unnoticed. Build once per CPU generation and copy the result to identical servers.
2. Configure each matcher
/etc/sentinel/sentinel.env on matcher number 7 of 32:
NODE_ENV=production
PORT=4000
MONGO_URI=mongodb://sentinel_match:<password>@127.0.0.1:27017/sentinel_id?authSource=admin&tls=true
JWT_SECRET=<same as the application servers>
SHARD_ID=7
SHARD_COUNT=32
MATCH_NODE_KEY=<same secret as on the application servers>
FP_WORKERS=62 # leave two cores for the operating system
SHARD_COUNT must equal the number of entries in MATCH_NODES on the application servers, and SHARD_ID must match this server's position in that list (the first is 0).
The matcher database user needs read access to the templates collection only.
3. Service and memory
Use the same sentinel.service unit as the application servers. Templates are loaded at start-up and stay in memory: at 4 billion templates over 32 shards that is about 125 million templates and ~175 GB per server. Loading takes several minutes; restart matchers one at a time.
Raise the application runtime's memory limit for the matcher process in the unit file:
Environment=NODE_OPTIONS=--max-old-space-size=360000
4. Point the application servers at the shards
On every application server:
MATCH_NODES=https://m00.match.internal:4000,https://m01.match.internal:4000,...,https://m31.match.internal:4000
MATCH_NODE_KEY=<shared secret>
The order of the list defines the shard numbers. Never reorder it without re-sharding, or templates will be looked for on the wrong server.
5. Firewall rules (matching zone)
- Port
4000on matchers only from the application servers. The/internal/*routes must never be reachable from anywhere else. - Outgoing only to the data zone (
27017/27018).
6. Availability today and at national scale
| Current release | Delivered for national scale | |
|---|---|---|
| Copies of each shard | One matcher per shard; a failed matcher restarts and reloads its shard from the database | Two matchers per shard behind one internal address, with enrolments sent to both |
| Search strategy | Every search goes to every shard (optionally limited to one finger position) | Shortlist index first, then exact matching of the candidates only |
| Capacity added by | More shards (re-shard during a maintenance window) | More shards or more replicas, online |
See What is built today and what the project delivers.
7. Faces
In the current release face search runs inside the application servers, which suits galleries of millions. For billions of faces the project delivers the sharded face vector index (IVF-PQ) on 8 dedicated servers, as described in the architecture.