Skip to content

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

Pull the Docker Image

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

Replace 1.1.1 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:1.1.1
    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

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)

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

{
  "port": 6982,
  "number_of_threads": 4,
  "connection_timeout": 60,
  "keep_alive_request_number": 100,
  "client_max_body_size": 50,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "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_pool_size": 10
}

Service Parameters

Parameter Type Default Description
port integer 6982 Service listening port
number_of_threads integer 4 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 SSL certificates
engine_verbose boolean false Enable verbose HTTP logging
engine_pool_size integer 4 Connection pool size

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_pool_size": 20
}

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
}

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 @new_config.json

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

Note: Parameters like port and number_of_threads that require a service restart to take effect will be ignored during hot updates. The config update is not persistent; changes will be lost on restart. To make permanent changes, update the config file on disk, then restart the service.

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:

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