Installation Guide

Compatibility Notice

IMPORTANT - BREAKING CHANGE (2.0.0)

Starting in version 2.0.0, the REST payload contract for fingerprint operation endpoints changed and is not backward compatible with 1.x.x clients. Plan client migration before upgrading service images.

Legacy public routes POST /api/v1/finger/create-template and POST /api/v1/finger/verify are no longer exposed in 2.0.0.

Prerequisites

Before installing Facephi Finger Service, ensure:

Docker is installed and running
You have a valid Facephi license file
You have access to the Facephi Docker registry

Docker Registry Access

docker login facephicorp.jfrog.io

Use credentials provided by Facephi.

License Connectivity Requirements

Online Activation

Online activation is available only in connected environments.

The deployment image already bundles the required fingerprint processing components through Conan packaging, so no additional runtime files need to be mounted manually.

The server must have Internet connectivity.
Outbound HTTPS access to the licensing endpoints assigned to the deployment is required.

Firewall Configuration

If outbound traffic is restricted, request the exact allowlist for your deployment from Facephi before installation.

Installation

Pull the Docker Image

docker pull facephicorp.jfrog.io/docker-core-pro-fphi/facephi-finger-service:2.1.0

Prepare Directories

mkdir -p ~/facephi_finger/{license,config,logs}

Place License File

Copy your license file to:

cp your-license.lic ~/facephi_finger/license/license.lic
chmod 644 ~/facephi_finger/license/license.lic

The service default license path is /app/license/license.lic.

Docker Compose Deployment

Create a docker-compose.yml file:

services:
  finger-service:
    image: facephicorp.jfrog.io/docker-core-pro-fphi/facephi-finger-service:2.1.0
    container_name: facephi-finger-service
    ports:
      - "6982:6982"
    volumes:
      - ~/facephi_finger/license:/app/license
      - ~/facephi_finger/config:/app/config
      - ~/facephi_finger/logs:/app/logs
    environment:
      - FACEPHI_FINGER_ENGINE_ROLE=master
      - FACEPHI_FINGER_ENGINE_SERVICES=Master,FingerTC,Verifier
      - FACEPHI_FINGER_ENGINE_MASTER=127.0.0.1
    restart: unless-stopped

Start the service:

docker compose up -d

Verify Deployment

# Check container status
docker ps | grep finger-service

# Check health endpoint
curl http://localhost:6982/api/v1/finger/health

# Check version endpoint
curl http://localhost:6982/api/v1/finger/version

# Check metrics endpoint
curl http://localhost:6982/api/v1/finger/metrics

Configuration File

Default configuration file path inside the container:

/app/config/config.json

Example:

{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_path": "/app/logs",
  "logger_level": "info",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080"
}

Environment Variables

Service Runtime Variables

Prefix: FACEPHI_FINGER_REST_

Common variables:

FACEPHI_FINGER_REST_PORT
FACEPHI_FINGER_REST_NUMBER_OF_THREADS
FACEPHI_FINGER_REST_CONNECTION_TIMEOUT
FACEPHI_FINGER_REST_KEEP_ALIVE_REQUEST_NUMBER
FACEPHI_FINGER_REST_CLIENT_MAX_BODY_SIZE
FACEPHI_FINGER_REST_LOGGER_PATH
FACEPHI_FINGER_REST_LOGGER_LEVEL
FACEPHI_FINGER_REST_LOGGER_ROTATION
FACEPHI_FINGER_REST_LOGGER_MAX_FILES

Fingerprint Processing Variables

Prefix: FACEPHI_FINGER_ENGINE_

Variables:

FACEPHI_FINGER_ENGINE_URL
FACEPHI_FINGER_ENGINE_CONN_TIMEOUT
FACEPHI_FINGER_ENGINE_REQ_TIMEOUT
FACEPHI_FINGER_ENGINE_MAX_RETRIES
FACEPHI_FINGER_ENGINE_RETRY_DELAY
FACEPHI_FINGER_ENGINE_VERIFY_SSL
FACEPHI_FINGER_ENGINE_VERBOSE
FACEPHI_FINGER_ENGINE_POOL_SIZE
FACEPHI_FINGER_ENGINE_ROLE
FACEPHI_FINGER_ENGINE_SERVICES
FACEPHI_FINGER_ENGINE_MASTER

Cluster-Oriented Deployment

For a multi-node topology:

Use one master node (FACEPHI_FINGER_ENGINE_ROLE=master) with public API exposure.
Use worker nodes (FACEPHI_FINGER_ENGINE_ROLE=worker) for engine workload scaling.
Set all nodes to point to the same FACEPHI_FINGER_ENGINE_MASTER address.

In worker role, only management endpoints are exposed.

Management endpoints include health, version, metrics, and config.

Usage Counters

The GET /api/v1/finger/metrics endpoint reports usage counters for successful public fingerprint operations.

To enable counters:

Add metadata key ActivateUsageCounters=true in the license used by the service.
Define meter attributes FingerExtractCounter and FingerAuthenticateCounter.

The response includes:

usageCountersEnabled
extractCount
authenticateCount
totalCount

totalCount is always computed as extractCount + authenticateCount.

Dynamic Configuration Updates

Use the config endpoint to apply runtime updates:

curl -X POST http://localhost:6982/api/v1/finger/config \
  -H "Content-Type: application/json" \
  -d '{"config_json_string":"{\"engine_pool_size\":8,\"engine_request_timeout\":45000}"}'

Important notes:

Runtime updates are in-memory and are not persisted automatically to config.json.
To keep changes after restart, update the file mounted in /app/config/config.json.

Troubleshooting

Service Does Not Start

Validate that /app/license/license.lic exists in the container.
Check container logs:

docker logs facephi-finger-service

Health Endpoint Reports Errors

Verify license validity.
Verify connectivity and startup timing for the fingerprint processing components.
Check configured engine role and services values.

Finger Endpoints Not Available

If /extract or /authenticate are unavailable, confirm the role:

FACEPHI_FINGER_ENGINE_ROLE must be master.

Metrics Endpoint Validation

If usage counters are expected but values remain unchanged:

Confirm GET /api/v1/finger/metrics returns usageCountersEnabled: true.
Confirm license metadata includes ActivateUsageCounters=true.
Confirm license meter names match exactly: FingerExtractCounter, FingerAuthenticateCounter.

Upgrade

# Pull target version
docker pull facephicorp.jfrog.io/docker-core-pro-fphi/facephi-finger-service:<new_version>

# Update image tag in compose
# Restart service
docker compose down
docker compose up -d

Always review release notes before upgrading.