Skip to content

System Requirements

Compatibility Notice

IMPORTANT - BREAKING CHANGE (2.0.0)

The REST payload contract for fingerprint operations changed in version 2.0.0 and is not backward compatible with 1.x.x client payloads.

Minimum Requirements

Component Requirement
OS Linux x86_64
CPU 4 cores
Memory 4 GB RAM
Disk 2 GB free space
Component Recommendation
OS Ubuntu LTS
CPU 8+ cores
Memory 8 GB+ RAM
Storage SSD for logs and container layers
Network Low-latency connectivity to required fingerprint processing services

Runtime and Build Constraints

  • Supported architecture: x86_64
  • Supported OS target: Linux
  • Container base runtime: Ubuntu 20.04

Service Architecture

The service acts as a stateless REST API adaptation layer:

Client Application -> Facephi Finger Service -> Facephi Fingerprint Processing

Characteristics:

  • No session state stored in the API layer
  • Public requests are validated and normalized before processing
  • Processing responses are translated back into the public contract
  • Suitable for horizontal scaling behind a load balancer

Endpoint Availability by Role

Role Endpoints
master extract, authenticate, health, version, metrics, config
worker health, version, metrics, config

Supported Image Formats (Public Fingerprint Endpoints)

For image-based requests on:

  • POST /api/v1/finger/extract (image)
  • POST /api/v1/finger/authenticate (image1, image2)

the supported fingerprint image formats are:

  • wsq
  • bmp
  • png
  • jpg
  • jp2

Configuration Model

Precedence Order

From highest to lowest priority:

  1. Environment variables
  2. config.json
  3. Service defaults

Runtime Configuration Groups

  • REST manager settings: listen port, threads, timeout, body size, logging
  • Processing settings: URL, connection/request timeout, retries, pool size, SSL verification
  • Topology settings: role (master/worker), processing services list, master node discovery address
  • Licensing usage counters: enabled by license metadata key ActivateUsageCounters

Usage Counters

  • GET /api/v1/finger/metrics exposes usage counters for successful extract and authenticate operations.
  • Response fields are: usageCountersEnabled, extractCount, authenticateCount, totalCount.
  • License meter attributes used by the service are FingerExtractCounter and FingerAuthenticateCounter.
  • totalCount is computed as extractCount + authenticateCount.

Performance Considerations

Dimension Guidance
Throughput Scales with engine capacity and connection pool size
Latency Affected by engine request timeout and retries
Concurrency Influenced by number_of_threads and engine_pool_size
Payload size Controlled by client_max_body_size

Operational Notes

  • During container startup, processing services can require warm-up time.
  • Health checks validate service context, license, and processing readiness.
  • In cluster-oriented deployment, ensure consistent discovery configuration across nodes.

Security Recommendations

  • Deploy behind a reverse proxy or API gateway.
  • Restrict inbound access to trusted networks.
  • Use TLS termination at the gateway/load balancer.
  • Protect mounted license and config files with least-privilege permissions.
  • Enable SSL verification for processing backend communication when infrastructure supports it.

Logging and Monitoring

Use endpoints for liveness checks:

  • GET /api/v1/finger/health
  • GET /api/v1/finger/version
  • GET /api/v1/finger/metrics

Configure logs with:

  • logger_level
  • logger_path
  • logger_rotation
  • logger_max_files

Compatibility Notes

  • API payloads for fingerprint operations use the public 2.0.0 contract.
  • Internal field names are not exposed in public responses.
  • Management endpoint payloads are stable and documented in OpenAPI.