Skip to content

Installation Manual

1. Installation and deployment

The service is dockerized, and there is a docker image in a Facephi repository. To be able to download the image you must be login as following:

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

Download the image:

docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service:#VERSION#

Where #VERSION# is the version number that we want to download (e.g. 6.8.2).

2. docker-compose

One way to deploy the service is to create a docker-compose.yml file with the following content:

version: '3.7'

services:
  ocr-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-ocr-service:#VERSION#
    container_name: facephi-ocr-service
    ports:
      - "6982:6982"
    volumes:
      - ~/facephi_ocr_license:/service/license
      - ~/facephi_ocr_configuration:/service/config
      - ~/facephi_ocr_logs:/service/logs
      - ~/facephi_ocr_custom_templates:/service/custom_templates

Note the volume that is mounted in the container. This volume is used to store the license file. The facephi_ocr_configuration is optional, but allow you to configure the service. See the 2.2 Service section. The facephi_ocr_logs is optional, but allow you to save the logs in the local storage, avoiding to lose the logs when the docker is down. The facephi_ocr_custom_templates is optional, but allow you to add custom document templates. You can copy your custom templates in this folder and then configure the service to use them. See the 3.2 Service section.

Run the following command, inside the folder where the docker-compose.yml file is located, to deploy the service:

    docker compose up

3. Configuration

3.1 License

To use this service, you need to have a valid license file.

The license file could contain the following information:

LICENSE_TYPE=         # License type, can be MACHINE, SHARED or LOCAL
LICENSE_BEHAVIOUR=    # License behaviour, can be ONLINE or OFFLINE
LICENSE_KEY=          # License key
LICENSE_ID=           # Product ID
LICENSE_DATA=         # Product data
LICENSE_URLS=         # Comma-separated license server URLs. Only needed if LICENSE_TYPE is LOCAL
LICENSE_PATH_OFFLINE= # Path to a local file with data for offline activation. Only needed if LICENSE_TYPE is MACHINE and LICENSE_BEHAVIOUR is OFFLINE

The license file can be passed as a parameter to the service. By default the service will look for a file named /service/license/license.lic. In the case of the docker container, the configuration file could be located in a volume mounted in /service/license.

In order to be able to connect with our License servers you must add to your firewall's rules the following rules:

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

Then add the following DNS to your whitelist:

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

3.2 Service

The config file could contain the following information by default:

{
    "port": 6982,                     # Service port number.
    "number_of_threads": 1,           # The number of IO threads, 1 by default, if the value is set to 0, the number of threads is autodetected.
    "connection_timeout": 60,         # The lifetime of the connection without read or write.
    "keep_alive_request_number": 0,   # Set the maximum number of requests that can be served through one keep-alive connection.
                                      # After the maximum number of requests are made, the connection is closed.
                                      # The default value of 0 means no limit.
    "client_max_body_size": 50,       # The maximum size of the body allowed in the requests in Mb.
                                      # The default value of 100 Mb.
    "logger_path" : "./logs",         # Set the path to store log files.
    "logger_level" : "trace",         # Possible values are [trace|debug|info|warning|error|critical|off].
    "logger_rotation" : "daily",      # Possible values are [hourly|daily].
    "logger_max_files" : 31,          # The default value of 0 means no limit.
    "processor_threads_pool_size": 2, # The number of threads in the pool for processing document images in parallel.
                                      # By default, it is set to 2. If the value is set to 0, the number of threads is autodetected.
    "pipeline_threads_pool_size": 1,  # The number of threads in the pool for processing inferences in parallel when executing the pipeline.
                                      # By default, it is set to 1.
    "global_threads_pool_size": 1,    # The number of threads in the pool for creating interpreters in parallel.
                                      # By default, it is set to 1.
    "document_interpreter_version": 1,# The version of the document interpreter to be used. 1 old version, 2 new version.
                                      # By default, it is set to 1.
    "config_path" : "data",              # Path to the folder that contains the models, templates and other configuration and resources files.
    "document_interpreter_use_universal": 0,  # By default, it is 0 (use legacy output format). If 1, use universal one.
    "templates_path" : "data/templates"  # Path to the folder that contains the templates.
}

The config file can be passed as a parameter to the service. By default the service will look for a file named /service/config/config.json. In the case of the docker container, the configuration file could be located in a volume mounted in /service/config.

All the parameters are optional. If some parameter is not present, the default value will be used instead.

document_interpreter_version

There are two distinct interpreters available for processing Identity Cards and Foreign Cards.

These interpreters differ in the following aspects:

  • Supported countries
  • Output format
  • Available fields

Supported Countries:

Version 1 officially supports identity documents from Argentina (ARG) and Mexico (MEX).

Version 2 officially supports a broader range of countries, including:

  • Canada (CAN)
  • Paraguay (PRY): PRY I v3, PRY I v2.
  • Peru (PER): PER I v5, PER I v2

Version 2 also has limited support for:

  • Argentina (ARG)
  • Bolivia (BOL)
  • Brazil (BRA)
  • Chile (CHL)
  • Colombia (COL)
  • Costa Rica (CRI)
  • Dominican Republic (DOM)
  • Ecuador (ECU)
  • El Salvador (SLV)
  • Guatemala (GTM)
  • Honduras (HND)
  • Jordan (JOR)
  • Mexico (MEX)
  • Nicaragua (NIC)
  • Nigeria (NGA)
  • Panama (PAN)
  • South Africa (ZAF)
  • South Korea (KOR)
  • Spain (ESP)
  • Uganda (UGA)
  • Uruguay (URY)
  • Vietnam (VNM)

Recommendation: Use Version 1 for documents from Argentina and Mexico, and Version 2 for documents from all other countries.

Output Format:

Each version structures its output data differently.

Version 1 organizes the extracted data using the front and back keys to distinguish between the front and reverse sides of the document:

{
    "back": {
        "Address": "REDACTED",
        ...
    },
    "front": {
        "DateOfBirth": "01/09/1972",
        ...
    }
}

Version 2, on the other hand, uses a nested structure under the reader key, with numeric identifiers to represent each side of the document (0 for front and 1 for back), along with more detailed path-style keys:

{
    "reader": {
        "0/MRZ/DateOfBirth": "01/09/1972",
        ...
        "1/ML/Address": "Redacted",
        ...
    }
}

Field Differences:

In addition to variations in data structure, there may be differences in the fields themselves. Some fields may exist in only one version, and even when a field appears in both, its content may vary between the two versions.