> 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/backend1n/installation/installation_instructions.md).

# Instalación y despliegue del servicio

## 1. Instalación y despliegue

El servicio está dockerizado y existe una imagen Docker en un repositorio de Facephi.

```bash
docker login facephicorp.jfrog.io
user: username
pass: token
```

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
```

Donde `#VERSION#` es la etiqueta de la versión concreta que queremos descargar. La etiqueta lleva el prefijo `v` (por ejemplo, `v5.0.0`).

## 2. Bases de datos.

Previamente al inicio del servicio, el administrador deberá crear y configurar las bases de datos pertinentes, así como un usuario específico para el servicio. Este **usuario/contraseña deberá indicarse en la cadena de conexión**. La tecnología de BD que utilizará el servicio se decidirá en el arranque, en función del prefijo de esta cadena de conexión.

## 2.1 MongoDB

Se deberá crear la variable de entorno `DATABASE_CONNECT_STRING` apuntando a MongoDB.

```bash
# MongoDB prefijos aceptados.
# mongodb://
# mongodb+srv://
export DATABASE_CONNECT_STRING=mongodb://user:pass@localhost:32902/?directConnection=true&serverSelectionTimeoutMS=5000
```

El propio servicio creará una base de datos denominada `db-backend`, si no existe previamente. En ella alojará tres colecciones:

* `media` para almacenar imágenes.
* `patterns` para almacenar patrones biométricos.
* `collections` para las colecciones creadas mediante `POST /collections` (desde la versión 5.0.0). Si está vacía al arrancar, el servicio la rellena a partir de los `collectionId` presentes en `patterns` (ver las notas de la versión 5.0.0).

El usuario de la cadena de conexión necesita permisos de lectura y escritura sobre estas tres colecciones.

## 2.2 PostgreSQL

De igual forma se debe crear la variable de entorno `DATABASE_CONNECT_STRING` apuntando a PostgreSQL.

```bash
# PostgreSQL prefijos aceptados.
# postgres://
# postgresql://
export DATABASE_CONNECT_STRING=postgresql://user:pass@localhost:32903/db_backend
```

El caso de PostgreSQL difiere ligeramente de MongoDB. Una BD con el nombre `db_backend` debe haber sido creada previamente por el administrador del sistema. PostgreSQL dificulta la creación de bases de datos desde el propio cliente. Un ejemplo de los comandos previos que debería ejecutar el administrador sería:

```bash
sudo -u postgres psql -c "CREATE ROLE backend1n WITH LOGIN PASSWORD 'backend1n';"
sudo -u postgres psql -c "CREATE DATABASE db_backend OWNER backend1n;"
sudo -u postgres psql -d db_backend -c "GRANT ALL ON SCHEMA public TO backend1n;"
```

Dentro de la BD PostgreSQL, el servicio creará tres tablas, al igual que ocurre con MongoDB:

* `media` para almacenar imágenes.
* `patterns` para almacenar patrones biométricos.
* `collections` para las colecciones creadas mediante `POST /collections` (desde la versión 5.0.0), con la misma regla de migración automática.

El usuario de la cadena de conexión necesita permisos para crear tablas y leer/escribir en ellas.

## 3. docker-compose

Una forma de desplegar el servicio es crear un archivo `docker-compose.yml` con el siguiente contenido, cambiando el valor de las variables según sea necesario. El ejemplo incluye una base de datos MongoDB; si usas una base de datos externa, elimina el servicio `mongo` y apunta `DATABASE_CONNECT_STRING` a ella (recuerda que dentro del contenedor `127.0.0.1` es el propio contenedor, no el equipo anfitrión).

```yaml
services:
  backend1n-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config:/service/config
    environment:
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
```

Primero, debes crear un directorio de usuario con permisos de lectura y escritura, por ejemplo `~/backend1n/config`, y colocar estos dos archivos:

* El archivo de licencia de SelphID `license.lic` (obligatorio). Es una licencia online: el equipo necesita salida a los servidores de licencias indicados en el apartado 4.4. Sin una licencia válida el servicio no arranca: escribe el motivo en el log y termina con código de salida 1.
* El archivo de configuración del servicio `config.json` (opcional).

Además, debes proporcionar la variable de entorno `DATABASE_CONNECT_STRING` con la cadena de conexión a la base de datos (por ejemplo, `mongodb://mongo:27017`). Si no está definida, el servicio no arranca. Para propósitos de depuración, puedes deshabilitar las operaciones de base de datos proporcionando el valor `no-db`. Ejemplo: `DATABASE_CONNECT_STRING=no-db`

Ejecuta el siguiente comando, dentro de la carpeta donde se encuentra el archivo `docker-compose.yml`, para desplegar el servicio:

```
docker compose up
```

## 4. Configuración adicional

Siguiendo los pasos de la **sección 2**, el servicio queda listo para arrancar. Si necesitas crear volúmenes adicionales para los distintos tipos de recursos, puedes seguir estas configuraciones adicionales.

### 4.1 Licencia

Puedes montar un volumen adicional y definir la variable de entorno `LICENSE_PATH`, en caso de que quieras instalar la licencia fuera del directorio de configuración habitual.

```yaml
services:
  backend1n-service:
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config/config.json:/service/config/config.json
      - ~/backend1n/license/license.lic:/service/license/license.lic
    environment:
      LICENSE_PATH: /service/license
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
```

> `LICENSE_PATH` es una carpeta (en el contenedor, `/service/license`) que contiene el archivo `license.lic`. En este ejemplo el archivo del anfitrión es `~/backend1n/license/license.lic`.

### 4.2 Configuración del servicio

Puedes especificar otra ubicación para el archivo `config.json` con los parámetros del servicio:

```yaml
services:
  backend1n-service:
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config:/service/config
      - ~/backend1n/custom:/service/custom
    environment:
      CONFIG_FILE: /service/custom/config.json
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
```

> `CONFIG_FILE` es la ruta, dentro del contenedor, al archivo de configuración. No montes ningún volumen sobre `/service` (contiene el ejecutable del servicio): usa un directorio distinto, como `/service/custom`.

Si no se especifica ningún `config.json`, se utilizarán estos datos por defecto:

```json
{
    "port": 6982,                   # Número de puerto del servicio.
    "number_of_threads": 0,         # El número de hilos de E/S, 0 = el número de núcleos de la CPU.
    "connection_timeout": 0,        # El tiempo de vida de la conexión sin lectura ni escritura.
    "keep_alive_request_number": 0, # Establece el número máximo de solicitudes que se pueden atender a través de una conexión keep-alive.
                                    # Una vez alcanzado el número máximo de solicitudes, la conexión se cierra.
                                    # El valor por defecto de 0 significa sin límite.
    "client_max_body_size": 100,    # El tamaño máximo del body permitido en las solicitudes, en Mb.
                                    # El valor por defecto es 100 Mb.
    "logger_path" : "./logs",       # Establece la ruta base donde se almacenan los archivos de log (ver nota más abajo sobre el anidado real de esta ruta).
    "logger_file_prefix" : "app",   # Prefijo usado para nombrar el directorio de logs de cada día.
    "logger_level" : "info",        # Los valores posibles son [trace|debug|info|warning|error|critical|off].
    "logger_rotation" : "daily",    # Los valores posibles son [hourly|daily].
    "logger_max_files" : 0,         # El valor por defecto de 0 significa sin límite.
    "auth_enabled": false,          # Habilita la autenticación JWT para los endpoints protegidos.
    "auth_jwt_secret": "",         # Secreto compartido utilizado para validar firmas JWT HS256.
    "auth_accept_authorization_header": true, # Acepta Authorization: Bearer <jwt>.
    "auth_accept_api_key_header": true,       # Acepta la cabecera de API key con el token JWT.
    "auth_api_key_header_name": "x-api-key", # Nombre de la cabecera de API key cuando está habilitada.
    "metrics_saturation_queue_p95_ms": 250,             # p95 (1 min) de tiempo en cola a partir del cual se considera saturado.
    "metrics_saturation_min_inflight_ratio": 1.0,       # Fracción de hilos configurados que deben estar ocupados para contar como saturación.
    "metrics_error_rate_warning": 0.05,                 # Tasa de error (5 min) a partir de la cual el servicio se reporta como degradado.
    "metrics_idle_rps_threshold": 0.01,                 # Peticiones/segundo (15 min) por debajo de las cuales el servicio se reporta como inactivo.
    "metrics_quality_alert_window_seconds": 900         # Ventana de tiempo para considerar relevante un fallo de extracción, búsqueda u operación de base de datos.
}
```

> **Ruta real de los archivos de log:** `logger_path` es solo la base. El archivo final se escribe en `<logger_path>/<logger_file_prefix>-<AAAA-MM-DD>/logs/app_<AAAA-MM-DD>.log` (un directorio nuevo cada día). Con `logger_rotation` = `hourly` el nombre del archivo incluye la hora (UTC): `app_<AAAA-MM-DD>_<HH>.log`. Por ejemplo, con los valores por defecto (`logger_path=/service/config`, `logger_file_prefix=app`), el log de hoy se escribe en `/service/config/app-2026-09-22/logs/app_2026-09-22.log`, es decir, dentro del directorio de configuración montado. Si defines `logger_path=./logs` (relativo a `/service`), el log se escribe en `./logs/app-2026-09-22/logs/app_2026-09-22.log`. Cada línea del log es un objeto JSON con, al menos, `timestamp`, `humanized_timestamp` y `level`.

> **Parámetros `metrics_*`:** son únicamente política de clasificación. No cambian lo que hace el servicio, solo cómo se resume un snapshot ya recogido en los campos `state.classification` y `alerts` de `GET /metrics`. Se leen una sola vez al arrancar, cuando se carga el `config.json`; `POST /config` no los modifica.

La autenticación JWT es opcional y está deshabilitada por defecto. Cuando está habilitada, `GET /health`, `GET /version`, `GET /metrics` y `GET /metrics/prometheus` permanecen públicos, mientras que el resto de endpoints requieren un JWT HS256 válido con una reclamación `exp` no caducada.

Reglas de la autenticación:

* El token se envía en `Authorization: Bearer <jwt>` (el esquema no distingue mayúsculas) y/o en la cabecera de API key (`x-api-key` por defecto, o el nombre indicado en `auth_api_key_header_name`; los nombres de cabecera no distinguen mayúsculas), según `auth_accept_authorization_header` y `auth_accept_api_key_header`. Si llegan ambas cabeceras, prevalece `Authorization`.
* Se rechazan los tokens firmados con otro secreto o con otro algoritmo (HS384, HS512, `alg: none`), sin `exp`, con `exp` no numérico, con `exp` caducado o con `nbf` en el futuro.
* Una solicitud no autenticada o con un token inválido responde `401` con el cuerpo `{"status":401,"error":"Unauthorized","message":"…","timeStamp":"…"}` y la cabecera `WWW-Authenticate: Bearer`. La autenticación se evalúa antes que la validación del cuerpo de la solicitud.
* Cada intento no autorizado se contabiliza en `unauthorized` de `GET /metrics`.

Cualquiera de estos parámetros puede establecerse mediante variables de entorno con el prefijo `FACEPHI_BACKEND1N_REST_` (el nombre de la clave en mayúsculas), con precedencia sobre el `config.json`:

```
FACEPHI_BACKEND1N_REST_PORT=6982
FACEPHI_BACKEND1N_REST_NUMBER_OF_THREADS=2
FACEPHI_BACKEND1N_REST_CONNECTION_TIMEOUT=0
FACEPHI_BACKEND1N_REST_KEEP_ALIVE_REQUEST_NUMBER=0
FACEPHI_BACKEND1N_REST_CLIENT_MAX_BODY_SIZE=100
FACEPHI_BACKEND1N_REST_LOGGER_PATH=./logs
FACEPHI_BACKEND1N_REST_LOGGER_FILE_PREFIX=app
FACEPHI_BACKEND1N_REST_LOGGER_LEVEL=info
FACEPHI_BACKEND1N_REST_LOGGER_ROTATION=daily
FACEPHI_BACKEND1N_REST_LOGGER_MAX_FILES=0
FACEPHI_BACKEND1N_REST_AUTH_ENABLED=false
FACEPHI_BACKEND1N_REST_AUTH_JWT_SECRET=shared-secret
FACEPHI_BACKEND1N_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
FACEPHI_BACKEND1N_REST_AUTH_ACCEPT_API_KEY_HEADER=true
FACEPHI_BACKEND1N_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
FACEPHI_BACKEND1N_REST_METRICS_SATURATION_QUEUE_P95_MS=250
FACEPHI_BACKEND1N_REST_METRICS_SATURATION_MIN_INFLIGHT_RATIO=1.0
FACEPHI_BACKEND1N_REST_METRICS_ERROR_RATE_WARNING=0.05
FACEPHI_BACKEND1N_REST_METRICS_IDLE_RPS_THRESHOLD=0.01
FACEPHI_BACKEND1N_REST_METRICS_QUALITY_ALERT_WINDOW_SECONDS=900
```

Adicionalmente, el SDK biométrico subyacente (SelphID) admite la variable de entorno `FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD` (opcional). Es el valor de similitud, entre `0` y `100`, a partir del cual el SDK considera positiva una autenticación facial. Por defecto es `65`. Esta variable **no filtra** los resultados de `POST /search/*` (que devuelven `similarity` entre 0 y 1): para descartar candidatos por debajo de un umbral, envía `options.minSimilarity` (p. ej. `0.65`).

Los parámetros de configuración de la autenticación JWT solo pueden establecerse en el arranque:

* Configúrelos en `config.json` o en las variables de entorno `FACEPHI_BACKEND1N_REST_AUTH_*` antes de que se inicie el servicio.
* `GET /config` nunca devuelve esas claves de autenticación JWT.
* `POST /config` rechaza esas claves con `400` y no puede utilizarse para modificarlas en tiempo de ejecución.

### 4.3 Ruta de depuración y de uso

Por último, puedes especificar un volumen/ruta concreto con permisos de lectura y escritura para la información de depuración del SDK y los datos de uso del SDK, mediante las variables de entorno `DEBUG_PATH` y `USAGE_PATH`. El SDK crea en ellas los archivos `selphidDebug.log`, `selphidUsage.db` y `cntrs.db`. Si no se indican, se escriben en `/service/config`:

```yaml
services:
  backend1n-service:
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config:/service/config
      - ~/backend1n/debug:/service/debug
      - ~/backend1n/usage:/service/usage
    environment:
      DEBUG_PATH: /service/debug
      USAGE_PATH: /service/usage
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
```

### 4.4 Configuración de red

Para poder conectar con nuestros servidores de licencias, debes añadir a las reglas de tu firewall las siguientes reglas:

| IP           | Puerto | Tipo   |
| ------------ | ------ | ------ |
| 52.223.22.71 | 443    | TCP/IP |
| 35.71.188.31 | 443    | TCP/IP |
| 75.2.113.112 | 443    | TCP/IP |
| 99.83.149.57 | 443    | TCP/IP |

A continuación, añade los siguientes `DNS` a tu lista blanca:

```bash
https://api.cryptlex.com:443
https://api.eu.cryptlex.com:443
```
