> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/finger/installation/installation_instructions.md).

# 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

```bash
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

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

### Prepare directories

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

### Place the license file

Copy your license file to:

```bash
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`:

```yaml
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:

```bash
docker compose up -d
```

## Verify the deployment

```bash
# 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:

```json
{
  "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:

```bash
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:

```bash
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

```bash
# 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.