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

# Service installation and deployment

## Prerequisites

Before installing IAD Service, make sure you have:

* Docker installed and running
* A valid Facephi license file
* Access to Facephi's Docker registry

## Access to the Docker registry

Log in to Facephi's Docker registry:

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

You'll need the credentials provided by Facephi.

## Installation

{% hint style="danger" %}
**Breaking change notice (3.0.0)** Version 3.0.0 is not backward compatible with 2.x integrations. Before upgrading a deployed client, review and update:

* the evaluation endpoint (`POST /api/v1/iad/evaluate` replaces `POST /api/v1/iad/liveness/evaluate`)
* the interpretation of `diagnostic`, which is now set to `NoAttack` or `Attack`
* the analysis of successful responses (`probability`, `score`, `faceProbability`, `sdkDuration` and `queueDuration` are no longer returned; the following are added: `transactionId` and `timestamp`)
* dashboards and alerts that read the `quality` block from `GET /api/v1/iad/metrics`, which changes from `quality.liveness` to `quality.detection`
* the handling of HTTP `503` (`ServiceUnavailable`): `responses from GET /api/v1/iad/health` when the service cannot process evaluations, and capture operations when the analysis engine does not respond
  {% endhint %}

### Download the Docker image

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:v3.0.0
```

Replace `3.0.0` with the desired version.

### Prepare the directories

Create the directories for the license, configuration, and logs:

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

### Place the license file

Copy your license file to the license directory:

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

## Deployment with Docker Compose

Create `docker-compose.yml`:

```yaml
version: '3.7'

services:
  iad-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:v3.0.0
    container_name: facephi-iad-service
    ports:
      - "6982:6982"
    volumes:
      - ~/facephi_iad/license:/app/license
      - ~/facephi_iad/config:/app/config
      - ~/facephi_iad/logs:/app/logs
    restart: unless-stopped
```

### Start the service

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

### Verify the deployment

```bash
# Check container status
docker ps | grep iad-service

# Check service health
curl http://localhost:6982/api/v1/iad/health

# View logs
docker logs facephi-iad-service
```

When starting up, the service obtains the license, starts the analysis engine bundled in the image, and waits at least 30 seconds for the engine to be ready before it begins accepting requests on the port `6982`. In the meantime, requests to the port receive no response. When the service is ready, the log shows these lines:

```
License initialized successfully from: /app/license/license.lic
IAD service 3.0.0 started
```

If the analysis engine is still loading after that time, the service starts anyway and logs `Engine failed to start after 2 attempts`; in that case, `GET /api/v1/iad/health` responds with HTTP `503` with `Engine health check failed: <detalle>` until the engine finishes loading. If the engine process exits during startup, the service exits with exit code `1` without opening the port (see “Recovery from analysis engine crashes”). If the license cannot be obtained, the service does not start and the container stops (see “Troubleshooting”).

### Stop the service

Stop the service with `docker stop facephi-iad-service` or `docker compose down`. The service receives the stop signal, shuts down cleanly with exit code `0` and releases the license it was using. If the process exits abruptly (for example, with `docker kill`, because Docker's stop timeout expires, or because the machine crashes), the license is not released at that moment.

### Recovery from analysis engine crashes

The analysis engine runs as a separate process inside the container. If that process exits (for example, because the system stops it due to insufficient memory), the service does not restart it: it stops accepting requests, releases the license, and exits with exit code `1`. Recovery depends on the deployment's restart policy, which starts the service and engine again from a clean state:

* With Docker Compose, keep `restart: unless-stopped`, as in the example above, or use `restart: on-failure`. With `docker run`, add `--restart unless-stopped`.
* In Kubernetes, the default pod policy (`restartPolicy: Always`) already restarts the container.

Docker does not restart a container just because it is `unhealthy`: its restart policies only take effect when the container exits. That is why the service exits instead of staying up without an engine.

If the engine stops responding but its process is still running, the service does not exit: `GET /api/v1/iad/health` and capture operations return HTTP `503` until the engine responds again. In Kubernetes, configure probes for `GET /api/v1/iad/health` to remove the instance from load balancing in the meantime and restart it if the engine does not recover. Set `timeoutSeconds` to more than 5 seconds, the maximum engine check duration:

```yaml
startupProbe:
  httpGet:
    path: /api/v1/iad/health
    port: 6982
  periodSeconds: 10
  timeoutSeconds: 6
  failureThreshold: 18
readinessProbe:
  httpGet:
    path: /api/v1/iad/health
    port: 6982
  periodSeconds: 10
  timeoutSeconds: 6
livenessProbe:
  httpGet:
    path: /api/v1/iad/health
    port: 6982
  periodSeconds: 20
  timeoutSeconds: 6
  failureThreshold: 3
```

* `startupProbe` allows up to 3 minutes for startup, because the service does not open the port until the engine has loaded (at least 30 seconds).
* `GET /api/v1/iad/health` also returns `503` when the license is no longer valid, so `livenessProbe` then restarts the container, which will not start again until the license is valid.

For any deployment, do not set the container's memory limit below 6 GB (see [Memory sizing](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/technical_specifications.md#dimensionamiento-de-memoria)): with less memory, the system stops the engine again after each restart.

## Experimental replay attack mitigation

The service can apply a freshness window to incoming capture payloads. This experimental protection is disabled by default.

* Enable it with `FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true`
* Set the freshness window with `FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>`
* Default freshness window: `300` seconds
* The analysis engine applies it only to `POST /api/v1/iad/evaluate` and `POST /api/v1/iad/evaluate/custom`
* When the freshness window is exceeded, `/evaluate` and `/evaluate/custom` return HTTP `400` with `message` equal to `Replay attack detected`
* It does not apply to `POST /api/v1/iad/extract`: the engine's `/extract_image` route only decrypts and extracts the facial image, without running the injection detection pipeline, so it does not check the freshness window and extraction is not rejected even if the capture is outside the window

This functionality is configured at startup using environment variables. It is not part of `config.json` and is not exposed through `GET|POST /api/v1/iad/config`.

Example with `docker run`:

```bash
docker run -d \
  -p 6982:6982 \
  -e FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true \
  -e FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=60 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:v3.0.0
```

Docker Compose example:

```yaml
services:
  iad-service:
    environment:
      FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED: "true"
      FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME: "60"
```

## License configuration

The license file must be located at `/app/license/license.lic` inside the container.

### License file format

```ini
LICENSE_TYPE=         # MACHINE, SHARED, or LOCAL
LICENSE_BEHAVIOUR=    # ONLINE or OFFLINE
LICENSE_KEY=          # Your license key
```

If `LICENSE_TYPE`, the service uses `SHARED`, and if `LICENSE_BEHAVIOUR`, it uses `ONLINE`. The combination `SHARED` + `OFFLINE` is not supported: the service will not start with it.

**Optional fields:**

* `LICENSE_URLS=` — Comma-separated URLs of the license servers (required for the LOCAL type; see [Offline licensing with a local server](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/installation/offline_licensing.md))
* `LICENSE_OFFLINE_CODE=` — Contents of the offline activation response file provided by Facephi (required for MACHINE + OFFLINE)
* `LICENSE_ADDRS=` — Comma-separated MAC addresses used to calculate the machine fingerprint for MACHINE licenses. All must exist on the container’s network interfaces; if any are missing, the license will not activate

`LICENSE_ID` and `LICENSE_DATA`, if present, are ignored by the service, which logs a warning. IAD product credentials are embedded at build time, so these fields must be omitted from deployment templates.

## Public API overview

{% hint style="danger" %}
**Compatibility note** The following routes correspond to the version 3.0.0 contract. Clients built for 2.x must be migrated before they can call this version correctly.
{% endhint %}

Operational endpoints exposed by the service:

* `POST /api/v1/iad/evaluate`
* `POST /api/v1/iad/evaluate/custom`
* `POST /api/v1/iad/extract`
* `GET /api/v1/iad/version`
* `GET /api/v1/iad/health`
* `GET /api/v1/iad/metrics`
* `GET /api/v1/iad/metrics/prometheus`
* `GET|POST /api/v1/iad/config`

## JWT authentication

JWT authentication is optional and disabled by default.

* Configure it at startup in `/app/config/config.json` with `auth_enabled`, `auth_jwt_secret`, `auth_accept_authorization_header`, `auth_accept_api_key_header` and `auth_api_key_header_name`
* Override these values with the environment variables `FACEPHI_IAD_REST_AUTH_*`
* When authentication is enabled, all endpoints except `/health`, `/version`, `/metrics` and `/metrics/prometheus` require a JWT signed with HS256 using `auth_jwt_secret` and the `exp` claim. A clock skew of 60 seconds is allowed
* Always define `auth_jwt_secret` when enabling authentication: if it is empty, all protected endpoints respond with HTTP `401` with `Authentication secret is not configured`
* `GET /api/v1/iad/config` never returns the JWT authentication keys
* `POST /api/v1/iad/config` rejects JWT authentication keys; manage them only at startup

Details on how to send the token and on the responses `401` are in the “JWT Authentication” section of the [service overview](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad.md).

Startup configuration example:

```json
{
  "auth_enabled": true,
  "auth_jwt_secret": "replace-with-secret",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key"
}
```

Example environment variables:

```bash
export FACEPHI_IAD_REST_AUTH_ENABLED=true
export FACEPHI_IAD_REST_AUTH_JWT_SECRET=replace-with-secret
export FACEPHI_IAD_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
export FACEPHI_IAD_REST_AUTH_ACCEPT_API_KEY_HEADER=true
export FACEPHI_IAD_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
```

### Firewall configuration for license validation

Add firewall rules to allow outbound HTTPS traffic to Facephi's license servers:

| IP           | Port | Protocol |
| ------------ | ---- | -------- |
| 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   |

**Allow HTTPS traffic to:**

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

## Service configuration

Create `/app/config/config.json` to customize the service behavior. The file is optional: if it does not exist, the service starts with the default values. Parameters you do not include retain their default values.

### Configuration file location

* **Default location:** `/app/config/config.json` (inside the container)
* **Mount an external file:** Use the volume mapping in docker-compose

### Full configuration example (current default values)

```json
{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "",
  "logger_file_prefix": "app",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "metrics_enabled": true,
  "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",
  "engine_health_max_age_seconds": 10,
  "metrics_saturation_queue_p95_ms": 250,
  "metrics_saturation_min_inflight_ratio": 1.0,
  "metrics_error_rate_warning": 0.05,
  "metrics_idle_rps_threshold": 0.01,
  "metrics_quality_alert_window_seconds": 900
}
```

### Service parameters

| Parameter                          | Type    | Default     | Description                                                                                                                                                                     |
| ---------------------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`                             | integer | 6982        | Service listening port                                                                                                                                                          |
| `number_of_threads`                | integer | 1           | Worker threads for request processing                                                                                                                                           |
| `connection_timeout`               | integer | 60          | Maximum time, in seconds, that an idle connection remains open                                                                                                                  |
| `keep_alive_request_number`        | integer | 0           | Maximum number of requests per keep-alive connection (0 = unlimited)                                                                                                            |
| `client_max_body_size`             | integer | 100         | Maximum request body size in MB. Larger requests receive HTTP `413`                                                                                                             |
| `logger_path`                      | string  | ""          | Directory where log files are written. Empty disables file logging; logs continue to be written to the container's standard output                                              |
| `logger_file_prefix`               | string  | "app"       | Prefix for the daily log folder within `logger_path` (`<prefix>-<YYYY-MM-DD>`, with the date in UTC). Characters other than letters, numbers, `-` and `_` are replaced with `_` |
| `logger_level`                     | string  | "info"      | Log level: `trace`, `debug`, `info`, `warning`, `error`, `critical` or `off`. An unrecognized value is interpreted as `off`                                                     |
| `logger_rotation`                  | string  | "daily"     | Log file rotation: `daily` or `hourly`. Any other value is interpreted as `daily`                                                                                               |
| `logger_max_files`                 | integer | 7           | Maximum number of log files to retain (0 = unlimited)                                                                                                                           |
| `metrics_enabled`                  | boolean | true        | Collects traffic, saturation, and latency counters published by `GET /api/v1/iad/metrics` and `GET /api/v1/iad/metrics/prometheus`. With `false`, these blocks are set to zero  |
| `auth_enabled`                     | boolean | false       | Requires JWT authentication for protected endpoints                                                                                                                             |
| `auth_jwt_secret`                  | string  | ""          | HS256 shared secret used to validate JWTs                                                                                                                                       |
| `auth_accept_authorization_header` | boolean | true        | Accepts `Authorization: Bearer <jwt>`                                                                                                                                           |
| `auth_accept_api_key_header`       | boolean | true        | Accepts JWTs in the configured API key header                                                                                                                                   |
| `auth_api_key_header_name`         | string  | "x-api-key" | Name of the header used when API key token extraction is enabled                                                                                                                |

### Engine parameters

| Parameter                       | Type    | Default                 | Description                                                                                                                                                                                                                                                     |
| ------------------------------- | ------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine_connection_timeout`     | integer | 10000                   | Connection timeout (ms)                                                                                                                                                                                                                                         |
| `engine_request_timeout`        | integer | 60000                   | Request timeout (ms)                                                                                                                                                                                                                                            |
| `engine_max_retries`            | integer | 3                       | Maximum number of retries for an engine request that receives no response (connection error or timeout) or receives a `5xx`, `408` or `429`. Does not apply to the engine health check at `GET /api/v1/iad/health`                                              |
| `engine_retry_delay`            | integer | 1000                    | Initial delay between retries (ms); doubles with each retry                                                                                                                                                                                                     |
| `engine_verify_ssl`             | boolean | false                   | Verifies SSL certificates for capture analysis                                                                                                                                                                                                                  |
| `engine_verbose`                | boolean | false                   | Enables detailed HTTP logging for capture analysis                                                                                                                                                                                                              |
| `engine_pool_size`              | integer | 4                       | Connection pool size                                                                                                                                                                                                                                            |
| `engine_url`                    | string  | `http://localhost:8080` | Base URL for the capture analysis runtime                                                                                                                                                                                                                       |
| `engine_health_max_age_seconds` | integer | 10                      | Number of seconds for which `GET /api/v1/iad/health` reuses the latest check of the analysis engine, whether it succeeded or failed. With `0`, it checks on every call. When the check expires, it is repeated with a single attempt and a maximum of 5 seconds |

### Operational metrics thresholds

These parameters only change how `GET /api/v1/iad/metrics` classifies the service status (`state.classification`) and which alerts it publishes; they do not change evaluation behavior. These are the only parameters that `POST /api/v1/iad/config` applies at runtime.

| Parameter                               | Type    | Default | Description                                                                                                                                                                           |
| --------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metrics_saturation_queue_p95_ms`       | integer | 250     | 95th percentile of queue latency (1 minute, ms) above which the queue is considered saturated                                                                                         |
| `metrics_saturation_min_inflight_ratio` | number  | 1.0     | Fraction of `number_of_threads` that in-flight requests must exceed for the service to be considered saturated                                                                        |
| `metrics_error_rate_warning`            | number  | 0.05    | 5-minute error rate ( `4xx` and `5xx`, excluding rejected captures with `Replay attack detected`) above which the service is classified as `degraded` and the alert `HIGH_ERROR_RATE` |
| `metrics_idle_rps_threshold`            | number  | 0.01    | 15-minute requests per second below which the service is classified as `idle`                                                                                                         |
| `metrics_quality_alert_window_seconds`  | integer | 900     | Window, in seconds, during which a capture that the analysis engine could not evaluate keeps the alert active `LOW_QUALITY`                                                           |

A value that cannot be parsed, or is negative, is discarded with a log warning: if it comes from an environment variable, the value from `config.json`is used, and if that is also invalid, the default value is used.

### Environment variables

Environment variables take precedence over `config.json`:

* Service parameters, JWT authentication parameters, and `metrics_*` thresholds are overridden with `FACEPHI_IAD_REST_<UPPERCASE PARAMETER>`, for example `FACEPHI_IAD_REST_NUMBER_OF_THREADS` or `FACEPHI_IAD_REST_METRICS_ERROR_RATE_WARNING`.
* Engine parameters are overridden with these variables:

| Parameter                       | Environment variable                        |
| ------------------------------- | ------------------------------------------- |
| `engine_url`                    | `FACEPHI_IAD_ENGINE_URL`                    |
| `engine_connection_timeout`     | `FACEPHI_IAD_ENGINE_CONN_TIMEOUT`           |
| `engine_request_timeout`        | `FACEPHI_IAD_ENGINE_REQ_TIMEOUT`            |
| `engine_max_retries`            | `FACEPHI_IAD_ENGINE_MAX_RETRIES`            |
| `engine_retry_delay`            | `FACEPHI_IAD_ENGINE_RETRY_DELAY`            |
| `engine_verify_ssl`             | `FACEPHI_IAD_ENGINE_VERIFY_SSL`             |
| `engine_verbose`                | `FACEPHI_IAD_ENGINE_VERBOSE`                |
| `engine_pool_size`              | `FACEPHI_IAD_ENGINE_POOL_SIZE`              |
| `engine_health_max_age_seconds` | `FACEPHI_IAD_ENGINE_HEALTH_MAX_AGE_SECONDS` |

The engine's boolean variables accept `true`, `TRUE`, `yes`, `YES` or `1`, and `false`, `FALSE`, `no`, `NO` or `0`. An invalid value in a `FACEPHI_IAD_ENGINE_*` variable is ignored with a warning in the log, and the value from `config.json` or the default value is retained.

`GET /api/v1/iad/config` does not reflect values set using environment variables: it shows those from `config.json` and the default values.

### Production configuration

For production deployments:

```json
{
  "port": 6982,
  "number_of_threads": 8,
  "connection_timeout": 60,
  "keep_alive_request_number": 1000,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "logger_rotation": "daily",
  "logger_max_files": 30,
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": true,
  "engine_verbose": false,
  "engine_pool_size": 20,
  "engine_url": "https://localhost:8080"
}
```

### Development configuration

For local development:

```json
{
  "port": 6982,
  "number_of_threads": 2,
  "logger_level": "debug",
  "logger_path": "/app/logs",
  "engine_connection_timeout": 5000,
  "engine_request_timeout": 30000,
  "engine_max_retries": 1,
  "engine_verify_ssl": false,
  "engine_verbose": true,
  "engine_pool_size": 2,
  "engine_url": "http://localhost:8080"
}
```

### Dynamic configuration updates

Some parameters can be updated without restarting the service:

```bash
# Update configuration
curl -X POST http://localhost:6982/api/v1/iad/config \
  -H "Content-Type: application/json" \
  -d '{"config_json_string":"{\"metrics_error_rate_warning\":0.1,\"metrics_quality_alert_window_seconds\":600}"}'

# Verify current configuration
curl http://localhost:6982/api/v1/iad/config
```

`POST /api/v1/iad/config` expects a JSON object with the field `config_json_string`, which contains the parameters to be modified, serialized as a JSON string; parameters that are not included retain their values. Only thresholds are applied at runtime `metrics_*` that `GET /api/v1/iad/metrics` uses to classify the service status. The remaining parameters, including `engine_*`, are read-only: they are configured at startup through `config.json` or environment variables and, although this endpoint accepts them, they do not change the service's behavior. The operation reference `POST /api/v1/iad/config` includes the complete parameter table. JWT authentication keys are rejected by this endpoint and must be configured only at startup.

* If a threshold's environment variable is defined (for example, `FACEPHI_IAD_REST_METRICS_ERROR_RATE_WARNING`), its value takes precedence over the value sent to `POST /api/v1/iad/config`.
* `GET /api/v1/iad/config` returns all values as strings (for example, `"metrics_error_rate_warning": "0.1"`).
* If `config_json_string` does not contain a valid JSON object, the request returns HTTP `400` with `message` equal to `Failed to load configuration from config_json_string` and the configuration does not change.

**Note:** Runtime updates are not persisted automatically. To make permanent changes, update the configuration file on disk and restart the service if necessary.

## Troubleshooting

### The service does not start

**Check the license file:**

```bash
docker exec facephi-iad-service ls -la /app/license/
```

**Check the logs:**

```bash
docker logs facephi-iad-service
```

If the license cannot be obtained at startup, the service exits and the container stops. The log indicates the reason with lines like these:

| Log line                                                                        | Cause                                                                             |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `Failed to open license file: /app/license/license.lic`                         | The license file is not in the mounted folder or cannot be read                   |
| `SHARED licenses with OFFLINE behaviour are not supported`                      | `license.lic` combines `LICENSE_TYPE=SHARED` with `LICENSE_BEHAVIOUR=OFFLINE`     |
| `License validation failed [License initialization]: <motivo> (code: <código>)` | The license is invalid or could not be validated (see “License validation fails”) |

### The service does not respond immediately after startup

The service waits at least 30 seconds for the built-in analysis engine to be ready before opening the port `6982`. Wait until you see `IAD service 3.0.0 started` in the log before sending requests or treating a startup probe as failed.

### `GET /api/v1/iad/health` responds `Engine health check failed`

`GET /api/v1/iad/health` responds with HTTP `503` because the integrated analysis engine is not responding. This usually happens while it is still finishing loading or when it is blocked.

* Check the log for `Engine failed to start after 2 attempts`.
* Check the container's available resources with `docker stats facephi-iad-service`.
* While the engine is unresponsive, `POST /api/v1/iad/evaluate`, `POST /api/v1/iad/evaluate/custom` and `POST /api/v1/iad/extract` return HTTP `503` with `message` equal to `Engine communication error: <detalle>`.

### The container restarts or exits with exit code `1`

The analysis engine process terminated, and the service stopped so that the restart policy can start it again (see “Recovering from analysis engine crashes”). The log indicates this with the following lines:

```
Engine process failed with exit code: 137
Engine process ended; stopping the service so that its restart policy starts it again
```

* Code `137` indicates that the system forcibly stopped the engine, usually because it ran out of memory. To confirm this, look for `Memory cgroup out of memory` in the machine's kernel log (`journalctl -k` or `dmesg`).
* If the container's memory limit is less than 6 GB, increase it (see [Memory sizing](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/technical_specifications.md#dimensionamiento-de-memoria)). With less memory, the engine will stop again after each restart.
* If the engine terminates during startup, the log also shows `Error: Engine process ended during startup` and the service never opens the port.

### License validation fails

* Check the license file permissions: `chmod 644 license.lic`
* Make sure the firewall allows outbound HTTPS traffic to the license servers
* Check the license expiration date
* Confirm that the license is for the IAD Service product

If the license becomes invalid while the service is already running, `GET /api/v1/iad/health` responds with HTTP `503` with `message` equal to `Invalid license: <motivo> (code: <código>)`, `POST /api/v1/iad/evaluate`, `POST /api/v1/iad/evaluate/custom` and `POST /api/v1/iad/extract` return HTTP `400` with the same `message` without analyzing the capture, `GET /api/v1/iad/version` adds `Invalid license` to the message and `GET /api/v1/iad/metrics` classifies the service as `unhealthy` with the alert `LICENSE_EXPIRED`.

### Performance issues

* Increase `engine_pool_size` to handle more concurrent requests
* Adjust `number_of_threads` based on the available CPU cores
* Monitor resource usage: `docker stats facephi-iad-service`
* Check the logs for timeout errors or retries

## Upgrade

To upgrade to a new version:

{% hint style="warning" %}
**Important** Upgrading from 2.x to 3.0.0 is an API migration with breaking changes, not a drop-in replacement. Validate all client calls against the new evaluation route and the request/response examples before promoting the deployment. See the [3.0.0 release notes](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/release_notes/3.0.0_release_notes.md).
{% endhint %}

```bash
# Pull new version
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:v3.0.0

# Update docker-compose.yml with new version
# Stop current service
docker compose down

# Start new version
docker compose up -d

# Verify upgrade
curl http://localhost:6982/api/v1/iad/version
```

**Always review the release notes before upgrading.**
