Installation and deployment of the service

1. Introduction

The service is containerized, and there is a Docker image in a Facephi repository.

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

docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-selphid-sdk:#VERSION#

Where #VERSION# is the specific version number you want to download (e.g. 6.21.0).

Important Starting with version 6.15.0, the Selphid-sdk Docker is offered in three variants.

• facephi-selphid-sdk:#VERSION#: Full service, as before.

• facephi-selphid-sdk:facial-#VERSION#: Facial extraction service, 1:1 and 1:N authentication.

• facephi-selphid-sdk:liveness-#VERSION#: Passive liveness service. The three variants are deployed in the same way, and the endpoints are consumed in the same way. The difference is that the variants facial and liveness do not respond to all endpoints, only to those related to their functionality.

2. docker-compose

One way to deploy the service is to create a file docker-compose.yml with the following content, modifying the value of the variables as needed.

version: '3.7'

services:
  selphid-service:
    ports:
      - "8080:8080"
    volumes:
      -  /home/user/selphid/config:/app/selphid-sdk/config
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-selphid-sdk:#VERSION#
    container_name: facephi-selphid-sdk

First, you must create a user directory with read and write permissions, for example /home/user/selphid/config, and place these two files:

• The License file license.lic (required).

• The service configuration file config.json (optional).

In the same directory, the service will write the log files.

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

docker compose up

3. Additional configuration

Following the steps in the section 2, the service is ready to start. If you need to create additional volumes for the different types of assets, you can follow these additional configurations.

3.1 License

You can mount an additional volume and define the environment variable LICENSE_PATH, if you want to install the license outside the usual configuration directory.

version: '3.7'

services:
  selphid-service:
    ports:
      - "8080:8080"
    volumes:
      -  /home/user/selphi/config:/app/selphid-sdk/config
      -  /home/user/license:/app/selphid-sdk/license
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-selphid-sdk:#VERSION#
    environment:
      LICENSE_PATH: /app/selphid-sdk/license
    container_name: facephi-selphid-sdk

LICENSE_PATH is a folder with the license.lic and read and write permissions. In this example, /home/user/license/license.lic.

3.2 Service

If you need to configure the service, you must provide a file config.json, as described in the section 2. If you want to place this file in an additional volume:

version: '3.7'

services:
  selphid-service:
    ports:
      - "8080:8080"
    volumes:
      -  /home/user/selphi/config:/app/selphid-sdk/config
      -  /home/user/service:/app/selphid-sdk/service
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-selphid-sdk:#VERSION#
    environment:
      CONFIG_FILE: /app/selphid-sdk/service/config.json
    container_name: facephi-selphid-sdk

CONFIG_FILE is the path to the configuration file in the additional volume.

If no config.json, these default values will be used:

{
    "port": 8080,                   # Service port number.
    "number_of_threads": 0,         # The number of IO threads, 0 = the number of CPU cores.
    "connection_timeout": 0,        # 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": 100,    # 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" : "info",        # Possible values are [trace|debug|info|warning|error|critical|off].
    "logger_rotation" : "daily",    # Possible values are [hourly|daily].
    "logger_max_files" : 0,         # The default value of 0 means no limit.
    "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"
}

JWT authentication is optional and disabled by default. When enabled, GET /api/v1/selphid/health and GET /api/v1/selphid/version remain public, while the rest of the endpoints require a valid HS256 JWT with an exp claim exp not expired.

Starting with version 6.19.0, these environment variables are added, which allow setting the values of config.json:

FACEPHI_SELPHID_REST_PORT=8080
FACEPHI_SELPHID_REST_NUMBER_OF_THREADS=2
FACEPHI_SELPHID_REST_CONNECTION_TIMEOUT=100
FACEPHI_SELPHID_REST_KEEP_ALIVE_REQUEST_NUMBER=0
FACEPHI_SELPHID_REST_CLIENT_MAX_BODY_SIZE=100
FACEPHI_SELPHID_REST_LOGGER_PATH=./logs
FACEPHI_SELPHID_REST_LOGGER_FILE_PREFIX=prefix
FACEPHI_SELPHID_REST_LOGGER_LEVEL=info
FACEPHI_SELPHID_REST_LOGGER_ROTATION=daily
FACEPHI_SELPHID_REST_LOGGER_MAX_FILES=0
FACEPHI_SELPHID_REST_AUTH_ENABLED=false
FACEPHI_SELPHID_REST_AUTH_JWT_SECRET=shared-secret
FACEPHI_SELPHID_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
FACEPHI_SELPHID_REST_AUTH_ACCEPT_API_KEY_HEADER=true
FACEPHI_SELPHID_REST_AUTH_API_KEY_HEADER_NAME=x-api-key

JWT authentication parameters can only be set at startup:

• Set them in config.json or in the environment variables FACEPHI_SELPHID_REST_AUTH_* before the service starts.

• GET /api/v1/selphid/config never returns those JWT authentication keys.

• POST /api/v1/selphid/config rejects those keys and cannot be used to modify them at runtime.

3.3 Debug and usage path

Finally, you can specify a specific volume/path with read and write permissions for the SDK debug information and the SDK usage data, using the environment variables DEBUG_PATH and USAGE_PATH:

version: '3.7'

services:
  selphid-service:
    ports:
      - "8080:8080"
    volumes:
      -  /home/user/selphi/config:/app/selphid-sdk/config
      -  /home/user/debug:/app/selphid-sdk/debug
      -  /home/user/usage:/app/selphid-sdk/usage
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-selphid-sdk:#VERSION#
    environment:
      DEBUG_PATH: /app/selphid-sdk/debug
      USAGE_PATH: /app/selphid-sdk/usage
    container_name: facephi-selphid-sdk