Installation Guide

Prerequisites

Before installing the IAD Service, ensure you have:

Docker installed and running
Valid Facephi license file
Access to Facephi Docker registry

Docker Registry Access

Login to the Facephi Docker registry:

docker login facephicorp.jfrog.io

You will need credentials provided by Facephi.

Installation

Breaking change notice (2.0.0) Version 2.0.0 is not backward compatible with 1.x.x integrations. Before upgrading a deployed client, review and update: - public endpoint paths - multipart request field names (file -> required capture; file-only requests are rejected) - successful response parsing (capture_liveness and related fields are no longer returned)

Pull the Docker Image

docker pull facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.0.0

Replace 2.0.0 with the desired version.

Prepare Directories

Create directories for license, configuration, and logs:

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

Place License File

Copy your license file to the license directory:

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

Docker Compose Deployment

Create docker-compose.yml:

version: '3.7'

services:
  iad-service:
    image: facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.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

docker compose up -d

Verify Deployment

# 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

Experimental Replay Attack Mitigation

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

Enable it with FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true
Adjust the freshness window with FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>
Default freshness window: 300 seconds
When the freshness window is exceeded, the public API returns HTTP 400 with message equal to Replay attack detected

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

Example with docker run:

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-core-pro-fphi/facephi-iad-service:2.0.0

Example with Docker Compose:

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

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

Optional fields:

LICENSE_URLS= — Comma-separated license server URLs (required for LOCAL type)
LICENSE_PATH_OFFLINE= — Path to offline activation file (required for MACHINE + OFFLINE)

LICENSE_ID and LICENSE_DATA, if present, are ignored by the service as of version 2.0.0. The IAD product credentials are embedded at build time, so these fields should be omitted from deployment templates.

Public API Summary

Compatibility note The routes below are the 2.0.0 contract. Clients built for 1.x.x must be migrated before they can call this version successfully.

Operational endpoints exposed by the service:

POST /api/v1/iad/liveness/evaluate
POST /api/v1/iad/extract
GET /api/v1/iad/version
GET /api/v1/iad/health
GET|POST /api/v1/iad/config

Firewall Configuration for License Validation

Add firewall rules to allow outbound HTTPS to Facephi 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 service behavior.

Configuration File Location

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

Complete Configuration Example (Current Defaults)

{
  "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_rotation": "daily",
  "logger_max_files": 7,
  "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"
}

Service Parameters

Parameter	Type	Default	Description
`port`	integer	6982	Service listening port
`number_of_threads`	integer	1	Worker threads for request handling
`connection_timeout`	integer	60	Connection timeout in seconds (0 = no timeout)
`keep_alive_request_number`	integer	0	Keep-alive requests (0 = disabled)
`client_max_body_size`	integer	100	Max request body size in MB
`logger_path`	string	""	Log file path (empty = stdout)
`logger_level`	string	"info"	Log level: trace, debug, info, warn, error
`logger_rotation`	string	"daily"	Log rotation: daily, hourly, size
`logger_max_files`	integer	7	Max log files to retain

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	Max retry attempts
`engine_retry_delay`	integer	1000	Delay between retries (ms)
`engine_verify_ssl`	boolean	false	Verify capture-analysis SSL certificates
`engine_verbose`	boolean	false	Enable verbose capture-analysis HTTP logging
`engine_pool_size`	integer	4	Connection pool size
`engine_url`	string	"http://localhost:8080"	Base URL of the capture-analysis runtime

Production Configuration

For production deployments:

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

{
  "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

Update configuration without restarting:

# Update configuration
curl -X POST http://localhost:6982/api/v1/iad/config \
  -H "Content-Type: application/json" \
  -d '{"config_json_string":"{\"engine_url\":\"http://localhost:8081\",\"engine_pool_size\":8}"}'

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

POST /api/v1/iad/config expects a JSON object with the config_json_string field, containing the full configuration serialized as a JSON string.

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

Troubleshooting

Service Won't Start

Check license file:

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

Check logs:

docker logs facephi-iad-service

License Validation Fails

Verify license file permissions: chmod 644 license.lic
Ensure firewall allows outbound HTTPS to license servers
Check license expiration date
Confirm license is for IAD Service product

Performance Issues

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

Upgrading

To upgrade to a new version:

Important Upgrading from 1.x.x to 2.0.0 is a breaking API migration, not a drop-in replacement. Validate all client calls against the new endpoint names and request/response examples before promoting the deployment.

# Pull new version
docker pull facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.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 release notes before upgrading.