> 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/sdks/backend-sdk/finger/installation/installation_instructions.md).

# Instalación y despliegue del servicio

## Aviso de compatibilidad

IMPORTANTE - CAMBIO INCOMPATIBLE (BREAKING CHANGE) (2.0.0)

A partir de la versión 2.0.0, el contrato de payload REST para los endpoints de operaciones de huella dactilar ha cambiado y no es compatible con clientes 1.x.x. Planifica la migración del cliente antes de actualizar las imágenes del servicio.

Las rutas públicas heredadas `POST /api/v1/finger/create-template` y `POST /api/v1/finger/verify` ya no están expuestas en la versión 2.0.0.

## Requisitos previos

Antes de instalar Facephi Finger Service, asegúrate de que:

* Docker está instalado y en ejecución
* Dispones de un archivo de licencia Facephi válido
* Tienes acceso al registro Docker de Facephi

## Acceso al registro Docker

```bash
docker login facephicorp.jfrog.io
```

Utiliza las credenciales proporcionadas por Facephi.

## Requisitos de conectividad de licencia

### Activación online

La activación online solo está disponible en entornos conectados.

La imagen de despliegue ya incluye los componentes de procesamiento de huella dactilar necesarios mediante empaquetado Conan, por lo que no es necesario montar manualmente archivos adicionales en tiempo de ejecución.

* El servidor debe disponer de conectividad a Internet.
* Se requiere acceso HTTPS saliente a los endpoints de licencia asignados al despliegue.

### Configuración del firewall

Si el tráfico saliente está restringido, solicita a Facephi la lista de acceso exacta para tu despliegue antes de la instalación.

## Instalación

### Descargar la imagen Docker

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

### Preparar directorios

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

### Colocar el archivo de licencia

Copia tu archivo de licencia en:

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

La ruta de licencia predeterminada del servicio es `/app/license/license.lic`.

## Despliegue con Docker Compose

Crea un archivo `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
      # Protección JWT opcional
      # - 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
```

Inicia el servicio:

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

## Verificar el despliegue

```bash
# Comprobar el estado del contenedor
docker ps | grep finger-service

# Comprobar el endpoint de salud
curl http://localhost:6982/api/v1/finger/health

# Comprobar el endpoint de versión
curl http://localhost:6982/api/v1/finger/version

# Comprobar el endpoint de métricas
curl http://localhost:6982/api/v1/finger/metrics
```

## Archivo de configuración

Ruta predeterminada del archivo de configuración dentro del contenedor:

* `/app/config/config.json`

Ejemplo:

```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"
}
```

## Variables de entorno

### Variables de tiempo de ejecución del servicio

Prefijo: `FACEPHI_FINGER_REST_`

Variables habituales:

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

La autenticación JWT es opcional y está deshabilitada por defecto. Cuando está habilitada, el servicio valida tokens HS256 con un claim `exp` no expirado.

Los endpoints públicos permanecen accesibles sin autenticación:

* `GET /api/v1/finger/health`
* `GET /api/v1/finger/version`
* Peticiones de preflight `OPTIONS`

Los endpoints protegidos requieren un JWT válido, por ejemplo mediante `Authorization: Bearer <jwt>` o la cabecera de API key configurada.

### Variables de procesamiento de huella dactilar

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

## Despliegue orientado a clúster

Para una topología multinodo:

* Utiliza un nodo master (`FACEPHI_FINGER_ENGINE_ROLE=master`) con exposición de la API pública.
* Utiliza nodos worker (`FACEPHI_FINGER_ENGINE_ROLE=worker`) para escalar la carga de procesamiento.
* Configura todos los nodos para que apunten a la misma dirección `FACEPHI_FINGER_ENGINE_MASTER`.

En el rol worker, solo se exponen los endpoints de gestión.

Los endpoints de gestión incluyen `health`, `version`, `metrics` y `config`.

## Contadores de uso

El endpoint `GET /api/v1/finger/metrics` informa de los contadores de uso de las operaciones públicas de huella dactilar completadas con éxito.

Para habilitar los contadores:

* Añade la clave de metadatos `ActivateUsageCounters=true` en la licencia utilizada por el servicio.
* Define los atributos de medición `FingerExtractCounter` y `FingerAuthenticateCounter`.

La respuesta incluye:

* `usageCountersEnabled`
* `extractCount`
* `authenticateCount`
* `totalCount`

`totalCount` siempre se calcula como `extractCount + authenticateCount`.

## Actualizaciones dinámicas de configuración

Utiliza el endpoint de configuración para aplicar actualizaciones en tiempo de ejecución:

```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}"}'
```

Notas importantes:

* Las actualizaciones en tiempo de ejecución son en memoria y no se persisten automáticamente en `config.json`.
* Para conservar los cambios tras un reinicio, actualiza el archivo montado en `/app/config/config.json`.
* La configuración de autenticación JWT son ajustes de arranque; actualiza `config.json` o las variables de entorno y reinicia el servicio.

## Resolución de problemas

### El servicio no arranca

* Valida que `/app/license/license.lic` existe en el contenedor.
* Revisa los logs del contenedor:

```bash
docker logs facephi-finger-service
```

### El endpoint de salud reporta errores

* Verifica la validez de la licencia.
* Verifica la conectividad y el tiempo de arranque de los componentes de procesamiento de huella dactilar.
* Comprueba los valores configurados de rol y servicios del engine.

### Los endpoints de huella dactilar no están disponibles

Si `/extract` o `/authenticate` no están disponibles, confirma el rol:

* `FACEPHI_FINGER_ENGINE_ROLE` debe ser `master`.

### Validación del endpoint de métricas

Si se esperan contadores de uso pero los valores permanecen sin cambios:

* Confirma que `GET /api/v1/finger/metrics` devuelve `usageCountersEnabled: true`.
* Confirma que los metadatos de la licencia incluyen `ActivateUsageCounters=true`.
* Confirma que los nombres de medición de la licencia coinciden exactamente: `FingerExtractCounter`, `FingerAuthenticateCounter`.

## Actualización

```bash
# Descargar la versión de destino
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:<new_version>

# Actualizar la etiqueta de la imagen en el compose
# Reiniciar el servicio
docker compose down
docker compose up -d
```

Revisa siempre las notas de versión antes de actualizar.