Service installation and deployment

Compatibility notice

IMPORTANT - INCOMPATIBLE CHANGE (BREAKING CHANGE) (2.0.0)

As of version 2.0.0, the REST payload contract for the Fingerprint operation endpoints has changed and is not compatible with 1.x.x clients. Plan the client migration before updating the service images.

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

Prerequisites

Before installing Facephi Finger Service, make sure that:

• Docker is installed and running

• You have a valid Facephi license file

• You have access to the Facephi Docker registry

Access to the Docker registry

docker login facephicorp.jfrog.io

Use the credentials provided by Facephi.

License connectivity requirements

Online activation

Online activation is only available in connected environments.

The deployment image already includes the necessary Fingerprint processing components via Conan packaging, so there is no need to manually mount additional files at runtime.

• The server must have Internet connectivity.

• Outbound HTTPS access is required to the license endpoints assigned to the deployment.

Firewall configuration

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

Installation

Download the Docker image

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

Prepare directories

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

Place the 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's default license path is /app/license/license.lic.

Docker Compose deployment

Create a file docker-compose.yml:

services:
  finger-service:
    image: facephicorp.jfrog.io/docker-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
      # Optional JWT protection
      # - FACEPHI_FINGER_REST_AUTH_ENABLED=true
      # - FACEPHI_FINGER_REST_AUTH_JWT_SECRET=shared-secret
      # - FACEPHI_FINGER_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
      # - FACEPHI_FINGER_REST_AUTH_ACCEPT_API_KEY_HEADER=true
      # - FACEPHI_FINGER_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
    restart: unless-stopped

Start the service:

docker compose up -d

Verify the deployment

# Check the container status
docker ps | grep finger-service

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

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

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

Configuration file

Default path of the configuration file 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,
  "auth_enabled": false,
  "auth_jwt_secret": "",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key",
  "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

• FACEPHI_FINGER_REST_AUTH_ENABLED

• FACEPHI_FINGER_REST_AUTH_JWT_SECRET

• FACEPHI_FINGER_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER

• FACEPHI_FINGER_REST_AUTH_ACCEPT_API_KEY_HEADER

• FACEPHI_FINGER_REST_AUTH_API_KEY_HEADER_NAME

JWT authentication is optional and disabled by default. When enabled, the service validates HS256 tokens with a claim exp not expired.

Public endpoints remain accessible without authentication:

• GET /api/v1/finger/health

• GET /api/v1/finger/version

• Preflight requests OPTIONS

Protected endpoints require a valid JWT, for example via Authorization: Bearer <jwt> or the configured API key header.

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 a master node (FACEPHI_FINGER_ENGINE_ROLE=master) with public API exposure.

• Use worker nodes (FACEPHI_FINGER_ENGINE_ROLE=worker) to scale processing load.

• Configure all nodes to point to the same address FACEPHI_FINGER_ENGINE_MASTER.

In the worker role, only the management endpoints are exposed.

Management endpoints include health, version, metrics and config.

Usage counters

The endpoint GET /api/v1/finger/metrics reports the usage counters for successfully completed public Fingerprint operations.

To enable the counters:

• Add the metadata key ActivateUsageCounters=true to the license used by the service.

• Define the measurement attributes FingerExtractCounter and FingerAuthenticateCounter.

The response includes:

• usageCountersEnabled

• extractCount

• authenticateCount

• totalCount

totalCount is always calculated as extractCount + authenticateCount.

Dynamic configuration updates

Use the configuration 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 automatically persisted in config.json.

• To preserve the changes after a restart, update the file mounted at /app/config/config.json.

• JWT authentication configuration are startup settings; update config.json or the environment variables and restart the service.

Troubleshooting

The service does not start

• Verify that /app/license/license.lic exists in the container.

• Check the container logs:

docker logs facephi-finger-service

The health endpoint reports errors

• Verify the validity of the license.

• Verify the connectivity and startup time of the Fingerprint processing components.

• Check the configured engine role and services values.

The Fingerprint endpoints are not available

If /extract or /authenticate they are not available, confirm the role:

• FACEPHI_FINGER_ENGINE_ROLE must be master.

Metrics endpoint validation

If usage counters are expected but the values remain unchanged:

• Confirm that GET /api/v1/finger/metrics returns usageCountersEnabled: true.

• Confirm that the license metadata includes ActivateUsageCounters=true.

• Confirm that the license measurement names match exactly: FingerExtractCounter, FingerAuthenticateCounter.

Upgrade

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

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

Always review the Version notes before upgrading.