Skip to content

Configuration

The configuration via a YAML file has been introduced in the 6.1 Face SDK release, and from that point on, it's the preferred variant of the service parametrization. This type of configuration gives an ability to keep all the parameters in one place and change any of them without cluttering the global environment namespace.

Warning

The use of environment variables is deprecated, and we strongly recommend switching to a YAML-based configuration. In the near future, environment variables will stop functioning. The only exceptions are listed in the System Settings section.

In the Face SDK 6.1 version, there are two ways to configure the Web Service: via environment variables and via a YAML file. However, in the future releases, we'll migrate to a complete YAML-based configuration. For more details, see the Migration Guide.

Order of Precedence

The universal order of precedence for configuration options is as follows:

  1. Parameters in the config.yaml file, see How to Enable YAML Config
  2. Environment variables in the .env file
  3. Environment variables in OS
  4. Built-in defaults

Also, there are two exceptions. For security reasons, these parameters operate differently:

Environment variable YAML parameter
SQL_CONNECTION_STRING service.database.connectionString
AZURE_STORAGE_CONNECTION_STRING service.storage.az.connectionString

For them, the order of precedence is the following:

  1. Environment variables in OS
  2. Environment variables in the .env file
  3. Parameters in the config.yaml file

System Settings

The following environment variables must be configured at the system level and cannot be set in the YAML file.

Setting Default Description
REGULA_RETURN_SYSTEMINFO true When set to false or 0, there will be no system information returned in the /api/ping and /api/process response.
REGULA_LICENSE — Specifies the license as a Base64-encoded string.

How to Enable YAML Config

1. In the Face SDK Web Service installation folder, find the config.yaml.example file and rename it to config.yaml. Make sure not to move the file to other folders, it should be located in the root directory of the Web Service.

2. Populate the config.yaml file with proper values.

3. Restart the Service.

For docker, note that all relative paths below are subpaths to the installation folder or the /app/folder.

Structure

The YAML parameters are organized in two main sections: sdk and service. The tree-like structure, contents and individual parameters are described in detail further.

└── sdk
└── service
|   └── webServer
|   └── storage
|   └── database
|   └── detectMatch
|   └── liveness
|   └── search
|   └── houseKeeper

You can find the example of the configuration file at the bottom of the page.

sdk

In the sdk section, the general parameters for the Face SDK are collected.

sdk
└── compare
|   └── limitPerImageTypes
└── logging
|   └── level
└── detect
|   └── scenarios
|   |   └── scenario
|   |   └── quality
|   |   |   └── config
|   |   |   |   └── name     
|   |   |   |   └── range          
|   |   └── onlyCentralFace
|   |   └── attributes
|   |   |   └── config
|   |   |   |   └── name
Parameter Type Default Description
compare → limitPerImageTypes integer 2 A maximum number of matching inputs of each type for matching request.
logging → level string "INFO" Severity level for logging.
detect → scenarios → scenario string — Name of the scenario for face image quality assessment, see the Scenarios page for details.
detect → scenarios → quality → config map — A list of characteristics for face image quality assessment, see the Face Image Quality Assessment page for details.
quality → config → name string — The name of the characteristic, see the Сharacteristics section for details.
quality → config → range float — The range of applicable values for this characteristic, see the Сharacteristics section for details.
detect → scenarios → onlyCentralFace boolean — Whether to check only the central face in the image or all the faces.
detect → scenarios → attributes → config map — Attributes to evaluate, see the Attributes Evaluation page for details.
attributes → config → name string — The name of the attribute, here is the List of Attributes.

service

Settings for the Face SDK Web Service are located in the service sequence. The parameters are divided into the following sections:

service
|   └── webServer
|   └── storage
|   └── database
|   └── detectMatch
|   └── liveness
|   └── search

webServer

The webServer section contains configuration parameters that allow you to customize the behavior of the Web Server.

└── webServer
|   └── port
|   └── workers
|   └── timeout
|   └── demoApp
|   |  └── enabled
|   └── cors
|   |   └── origins
|   |   └── headers
|   |   └── methods
|   └── ssl
|   |   └── cert
|   |   └── key
|   |   └── tlsVersion
|   └── logging
|   |   └── level
|   |   └── formatter
|   |   └── access
|   |   |   └── console
|   |   |   └── path
|   |   └── app
|   |   |   └── console
|   |   |   └── path
|   └── metrics
|   |   └── enabled
|   |   └── path
Parameter Type Default Description
port integer 41101 Port number for the web server.
workers integer 1 Number of workers to process requests.
timeout integer 30 Number of seconds for the worker to process the request. Workers that remain idle for more than this number of seconds are killed and restarted.
demoApp → enabled boolean true Whether to enable the demo web application.
cors → origins string No default. This means that the web browser will allow requests to the web server from the same domain only. Origin of requests, allowed to use API. In case of several origins, we recommend specifying all origins in a comma-separated format instead of using a wildcard character *. For example, origin_1,origin_2,origin_3.
cors → headers string all headers Headers, allowed to read from the API. Specify comma-separated values as a single string (for example, "content-type,date").
cors → methods string "POST,PUT,GET,DELETE,PATCH,HEAD,OPTIONS" Methods, allowed to invoke on the API. Specify comma-separated values as single strings (for example, "GET,POST,PUT").
ssl → enabled boolean false Whether to enable a Secure Sockets Layer (SSL) for the web server. If the ssl section is present in the configuration file and includes the cert and key fields, SSL is enabled.
ssl → cert string "certs/tls.crt" Path to the SSL certificate file.
ssl → key string "certs/tls.key" Path to the SSL key file. Use a key file without a passphrase. A passphrase causes the web server to crash or infinitely await stdin.
ssl → tlsVersion string 1.2 Version of the TLS (Transport Layer Security) protocol to use for secure connections within the application. Available values: 1.0, 1.1, 1.2, 1.3.
logging map — See logging.
metrics → enabled boolean true
(for all OS except Windows)		 Whether to collect Prometheus metrics. See more details about available metrics on the Monitoring page.
metrics → path string metrics If metrics.enabled, specifies the custom file path to save metrics.
logging

There are 3 log types in our service:

  1. Access logs—standard HTTP access logs.
  2. Application logs—regular application logs, including errors and debug messages.
  3. Processing result logs store the processing input and results in JSON format. The location for the processing result logs is set separately for the modules, see the location section at detectMatch, liveness, and search. 
└── webServer
|   └── logging
|   |   └── level
|   |   └── formatter
|   |   └── access
|   |   |   └── console
|   |   |   └── path
|   |   └── app
|   |   |   └── console
|   |   |   └── path
Parameter Type Default Description
level string "INFO" Logging level. Available values: "ERROR", "WARN", "INFO","DEBUG".
formatter string "text" Logs format. Possible values: text or json. (Some log collectors require logs in JSON format.)
access map — The access setting controls whether access logs collection is enabled. If the access section is present in the config.yaml file and includes the console and path fields, the access logs are collected. If there is no access section in the config.yaml file, access logs are not collected.
access → console boolean true Whether to print access logs to a console.
access → path string "logs/access/facesdk-reader-access.log" Sets the path for the access log file.
app map — The app setting controls whether application logs collection is enabled. If the app section is present in the configuration file and includes the console and path fields, the application logs are collected. If there is no app section in the config.yaml file, application logs are not collected.
app → console boolean true Whether to print application logs to a console.
app → path string "logs/app/facesdk-reader-app.log" Sets the path to the file where the application logs will be saved.

storage

To save the processing results logs (for the Face Detection and Comparison modules), liveness assessment data (for the Liveness module), and identification binary data (for the Identification module), you need to configure storage. The supported storage types are described on the Storage page.

Setting up storage includes the next steps:

1. In service.storage, set the credentials for the storage type.

2. Storage buckets are configured separately within each feature section:

Amazon S3

The Face SDK Web Service can be configured to use Amazon S3 storage.

service
|   └── storage
|   |   └── type
|   |   └── s3
|   |   |   └── accessKey
|   |   |   └── accessSecret
|   |   |   └── region
|   |   |   └── secure
|   |   |   └── endpointUrl
Parameter Type Default Description
type string — The processing results logs storage type. Set the "s3" value to use Amazon S3 as the storage.
s3 → accessKey string — Access key for the S3 storage.
s3 → accessSecret string — Access secret for the S3 storage.
s3 → region string — Region for the S3 storage.
s3 → secure boolean true Whether to check the CA certificate.
s3 → endpointUrl string — S3-compatible storage endpoint URL.
Google Cloud Storage

The Face SDK Web Service can be configured to use Google Cloud Storage.

└── storage
|   └── type
|   └── gcs
|   |   └── gcsKeyJson
Parameter Type Default Description
type string — The processing results logs storage type. Set the "gcs" value to use Google Cloud Storage.
gcs → gcsKeyJson string "/etc/credentials/gcs_key.json" Path to the credentials file for Google Cloud Storage access.
Microsoft Azure

The Face SDK Web Service can be configured to use the Microsoft Azure storage.

└── storage
|   └── type
|   └── az
|   |   └── storageAccount
|   |   └── connectionString
Parameter Type Default Description
type string — The processing results logs storage type. Set the "az" value to use Microsoft Azure storage.
az → storageAccount string — Name of the Azure Storage account.
az → connectionString string — Connection string for Azure Storage.

Note that for this parameter, the order of precendence differs from the common one, see Order of Precedence.
File System

The Face SDK Web Service can be configured to use the file system.

└── storage
|   └── type
|   └── fs
Parameter Type Default Description
type string — The processing results logs storage type. Set the "fs" value to use file system as the storage.
fs string — File system settings, optional.

database

To use the Liveness and Identification modules of the Face SDK, you need to configure a database. The following database types and versions are supported:

Database Version
PostgreSQL 14 and higher
MariaDB Server 10.7 and higher (and its predecessor MySQL v8 and higher)
Oracle 19c and higher
SQLite
(not recommended for production solutions, not supported on Linux)		 3
Microsoft SQL SQL Server 2016 and higher
MongoDB 4.0 and higher

Info

  • For using SQLite on Linux, make sure to install the libsqlite3-dev package.

  • If you use PostgreSQL v13 and older, you need to add an extension by invoking the following script:

CREATE EXTENSION pgcrypto;

Info

Our system supports connecting to Oracle databases using service names. To enable this, install the Oracle Instant Client, set the appropriate paths, and configure the connection string with the service name. For more detailed instructions, refer to the config.yaml.example file in the Face SDK Web Service installation folder.

service
|   └── database
|   |   └── connectionString
|   |   └── passwordlessAuth
Connection string
Parameter Type Default Description
connectionString string — The connection string to the database by the pattern dialect://user:password@host/dbname[?key=value..]

Note that for the SQL database connection string, the order of precendence differs from the common one, see Order of Precedence.

For MariaDB and MySQL, password authentication via the ed25519 hash is supported. No additional configuration is required, and connectionString remains as described above.

See the sample connectionString values for different database systems below.

postgresql://<username>:<password>@127.0.0.1:5432/regula_db

mysql://<username>:<password>@127.0.0.1:5432/regula_db

mysql+pymysql://<username>:<password>@127.0.0.1:3306/regula_db

mysql+pymysql://<username>:<password>@127.0.0.1:3306/regula_db
  • Linux 
    sqlite:////opt/regula/face-reg-service/regula.db
  • Windows 
    sqlite:///c:/ProgramData/Regula/Face Processing Service/regula.db

mssql+pymssql://<username>:<password>@127.0.0.1:1433/regula_db

oracle+oracledb://system:admin@127.0.0.1:1521/FREE

oracle+cx_oracle://system:regulapassword@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=FREEDB1)))

mongodb://<username>:<password>@127.0.0.1:27017/regula_db?authSource=admin

When connecting to the database, the necessary tables will be created automatically if they do not already exist. If connecting to a previously used database, the tables that were created earlier will be used.

Passwordless authentication

Use the passwordlessAuth configuration to set passwordless authentication using cloud providers. Now, the option is available only for Azure SQL Database, but in the future releases more providers will be supported. 

└── passwordlessAuth
|   └── enabled
|   └── type 
|   └── az
|   |    └── scope
Parameter Type Default Description
passwordlessAuth → enabled boolean — Whether to enable the passwordless authentication.
passwordlessAuth → type string — Specifies the type of passwordless authentication; shoud be set to az for Azure.
az → scope string — Specifies the scope for which the access token is requested during authentication. For example, https://database.windows.net/.default

detectMatch

The detectMatch setting controls whether the Detection and Comparison modules are enabled for the web server. If the detectMatch block is present in the config.yaml file and includes the results field, processing results logging for the Detection and Comparison modules is enabled as well.

If there is no detectMatch section in the config.yaml file, the Detection and Comparison modules are not enabled.

service
|   └── detectMatch
|   |   └── enabled
|   |   └── results      
|   |   |   └── location
|   |   |   |   └── bucket   
|   |   |   |   └── container   
|   |   |   |   └── folder   
|   |   |   |   └── prefix
Parameter Type Default Description
enabled boolean false Whether to enable saving the processing result logs for the Face Detection and Face Comparison modules.
results → location map — Contains the storage data for the processing result logs for the Face Detection and Face Comparison modules. If not set, the processing result logs are not collected.
location → bucket string "faceapi-detect-match" The AWS S3 or GCS bucket name.
location → container string "faceapi-detect-match" The Azure Blob Storage container name.
location → folder string "faceapi-detect-match" The File System folder name.
location → prefix string — Prefix for the bucket or container. If the storage type is fs, the prefix is not considered. However, for all other storage types, it is supported. Optional.

liveness

The liveness setting controls whether the Liveness module is enabled for the web server. If the liveness block is present in the configuration file, Liveness is enabled by default.

To use the Liveness module, make sure to configure storage and a database, otherwise, the feature won't work. You can find detailed explanations of why this setup is necessary on the Architecture page.

service
|   └── liveness
|   |   └── enabled
|   |   └── consistency
|   |   └── ecdhSchema
|   |   └── hideMetadata
|   |   └── sessions
|   |   |   └── location
|   |   |   |   └── bucket
|   |   |   |   └── container
|   |   |   |   └── folder
|   |   |   |   └── prefix
Parameter Type Default Description
enabled boolean false Whether to enable the Liveness feature.

If there is no liveness section in the config.yaml file or if enabled: false is indicated, the Liveness module is not enabled.
consistency string eventual The consistency model: eventual or strong.
ecdhSchema string "default" ECDH scheme key.
hideMetadata boolean false Whether to prevent links to the selfie and video from being added to the GET /liveness?transactionId=<> request.
sessions → location map — Contains the storage data for the liveness assessment.
location → bucket string "faceapi-sessions" The AWS S3 or GCS bucket name.
location → container string "faceapi-sessions" The Azure Blob Storage container name.
location → folder string "faceapi-sessions" The File System folder name.
location → prefix string — Prefix for the bucket or container. If the storage type is fs, the prefix is not considered. However, for all other storage types, it is supported. Optional.

The search setting controls whether the Identification module is enabled for the web server. If the search block is present in the configuration file, Identification is enabled by default.

To use the Identification module, make sure to set up storage, database, and Milvus, otherwise, the feature won't work. You can find detailed explanations of why this setup is necessary on the Architecture page.

service
|   └── search
|   |   └── enabled
|   |   └── persons
|   |   |   └── location
|   |   |   |   └── bucket
|   |   |   |   └── container
|   |   |   |   └── folder
|   |   |   |   └── prefix
|   |   └── threshold
|   |   └── vectorDatabase
|   |   |   └── type
|   |   |   └── milvus
|   |   |   |   └── user
|   |   |   |   └── password
|   |   |   |   └── token
|   |   |   |   └── endpoint
|   |   |   |   └── consistency
|   |   |   |   └── reload
|   |   |   |   └── index
|   |   |   |   |   └── type
|   |   |   |   |   └── params
|   |   |   |   |   |   └── nlist
|   |   |   |   └── search
|   |   |   |   |   └── type
|   |   |   |   |   └── params
|   |   |   |   |   |   └── nprobe
Parameter Type Default Description
enabled boolean false Whether to enable the Identification module.

If there is no search section in the config.yaml file or if enabled: false is indicated, the Identification module is not enabled.
persons → location → bucket string "faceapi-persons" The AWS S3 or GCS bucket name.
persons → location → container string "faceapi-persons" The Azure Blob Storage container name.
persons → location → folder string "faceapi-persons" The File System folder name.
persons → location → prefix string — A prefix for the bucket or container. If the storage type is fs, the prefix is not considered. However, for all other storage types, it is supported.
threshold float 1.0 The similarity threshold for 1:N search.

The value should be between 0.0 and 2.0, where 0.0 is for returning results for only the most similar persons and 2.0 is for returning results for all the persons, even the dissimilar ones. Learn more
milvus

The Identification module requires Milvus to operate. Milvus installation includes Milvus operator, MinIO, etcd, pulsar components.

Milvus supports running your vector databases in the cloud, hosted on platforms like Google Cloud Platform (GCP) and Amazon Web Services (AWS). Trial credits are available in Ohio, but you can choose another region if needed.

To enable this support, use the corresponsing parameters in the YAML configuration file according to the description below. Note that all data is stored in a de-identified format, specifically as vectors.

For specific details, consult the Milvus documentation.

Parameter Type Default Description
vectorDatabase → type string milvus The vector database type, set "milvus".
milvus → user string — The user for connecting to the Milvus instance. If both user and password are provided, the system will include the corresponding header in every RPC call.
milvus → password string — The password corresponding to the specified user.
milvus → token string — Serves as the key for identification and authentication purposes. When a token is provided, the system adds the corresponding header to each RPC call. Users can use either user+password or token. If both are filled, the system logs in using user+password.
milvus → endpoint string http://localhost:19530 The endpoint URL for the Milvus instance.
milvus → consistency string "Bounded" The consistency level to use when searching in a collection. Options for consistency level include Strong, Bounded, Eventually, Session, and Customized.
milvus → reload boolean false If set to true, checks that collections for searching are in memory and loads them if not. If set to false, this option is disabled.
milvus → index map — Parameters for the index to achieve better search performance.
index → type string "IVF_FLAT" Index type, see the Milvus documentation for details.
index → params → nlist integer 128 Number of cluster units, see the IVF_FLAT article for details.
search → type string "L2" The similarity metric type, metrics used to measure similarity of vectors, see the Similarity Metrics article for details.
search → params → nprobe integer 5 Number of units to query, see the IVF_FLAT article for details.

houseKeeper

The houseKeeper configuration allows for automatic cleanup of data in both storage and the database, see Cleaning Up Data for details.

By default, houseKeeper is enabled, but the clearing of data related to search and liveness is disabled. This configuration means that the FaceAPI will only clean up data in the dtask and lock tables in the database, while the liveness and person tables will remain unaffected.

The HouseKeeper operates on a task-based system, where tasks are executed at regular intervals defined by the beatCadence parameter. During each interval, the system checks for any outdated data that needs to be cleaned up. The HouseKeeper is capable of synchronizing and distributing its tasks across multiple instances, even in multi-instance or multi-machine setups.

You can access statistics for the HouseKeeper tasks via the /api/task/statistics endpoint.

service
|   └── houseKeeper
|   |   └── enabled
|   |   └── beatCadence
|   |   └── keepFor
|   |   └── liveness
|   |   |   └── enabled
|   |   |   └── keepFor
|   |   └── search
|   |   |   └── enabled
|   |   |   └── keepFor
Parameter Type Default Description
enabled boolean true Whether the HouseKeeper is active.
beatCadence integer 10 The frequency at which the HouseKeeper will check for outdated data, seconds.
keepFor integer 14400 Time for keeping HouseKeeper statistics in the database, seconds. The default setting keeps statistics for 4 hours (14400 seconds).
liveness → enabled boolean false Whether to clean up the data related to liveness transactions.
liveness → keepFor integer 31536000 Time for keeping HouseKeeper statistics in the database, seconds. If liveness.enabled is set to true, by default the data is kept for 1 year (31536000 seconds).
search → enabled boolean false Whether to clean up the data related to search transactions.
search → keepFor integer 31536000 Time for keeping HouseKeeper statistics in the database, seconds. If search.enabled is set to true, by default the data is kept for 1 year (31536000 seconds).

Configuration File Example

config.yaml
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
sdk:
  compare:
    limitPerImageTypes: 2
  logging:
    level: "INFO"

service:
  webServer:
    port: 41101
    workers: 1
    timeout: 30

    demoApp:
      enabled: true

    cors:
      origins: "*"
      headers: "Content-Type,X-Client-Key"
      methods: "POST,PUT,GET,DELETE,PATCH,HEAD"

    ssl:
      enabled: false
      cert: "/opt/regula/STAR.regulaforensics.com.crt"
      key: "/opt/regula/STAR.regulaforensics.com.key"

    logging:
      level: "INFO"
      formatter: "text"

      access:
        console: true
        path: "logs/access/facesdk-reader-access.log"

      app:
        console: true
        path: "logs/app/facesdk-reader-app.log"

    metrics:
      enabled: true
      path: "metrics"


  storage:
      type: "s3"
      s3:
        accessKey: "<ACCESS_KEY>"
        accessSecret: "<ACCESS_SECRET>"
        region: "eu-central-1"
        secure: true

      gcs:
        gcsKeyJson: "/etc/credentials/gcs_key.json"

      az:
        storageAccount: "<AZURE_STORAGE_ACCOUNT>"
        connectionString: "<AZURE_CONNECTION_STRING>"

      fs:

  database:
      connectionString: "postgresql://<username>:<password>@127.0.0.1:5432/regula_db"
      #connectionString: "mysql://<username>:<password>@127.0.0.1:5432/regula_db"
      #connectionString: "mariadb+pymysql://<username>:<password>@127.0.0.1:3306/regula_db"
      #connectionString: "mysql+pymysql://<username>:<password>@127.0.0.1:3306/regula_db"
      #connectionString: "sqlite:///c:/ProgramData/Regula/Face Processing Service/regula.db"
      #connectionString: "mssql+pymssql://<username>:<password>@127.0.0.1:1433/regula_db"
      #connectionString: "oracle+oracledb://system:admin@127.0.0.1:1521/FREE"
      #connectionString: "oracle+cx_oracle://system:regulapassword@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=FREEDB1)))"
      #connectionString: "mongodb://<username>:<password>@127.0.0.1:27017/regula_db?authSource=admin"
      passwordlessAuth:
        enabled: true
        type: "az"
          scope: "https://database.windows.net/.default"

  detectMatch:
    enabled: true
    results:
      location:
        bucket: "faceapi-detect-match"
        container: "faceapi-detect-match"
        folder: "faceapi-detect-match"

  liveness:
    enabled: true
    ecdhSchema: "default"
    hideMetadata: false
    sessions:
      location:
        bucket: "faceapi-sessions"
        container: "faceapi-sessions"
        folder: "faceapi-sessions"

  search:
    enabled: true
    persons:
      location:
        bucket: "faceapi-persons"
        container: "faceapi-persons"
        folder: "faceapi-persons"

    threshold: 1.0

    vectorDatabase:
      type: milvus
      milvus:
        user: ""
        password: ""
        token: ""
        endpoint: "http://localhost:19530"
        consistency: "Bounded"
        reload: false
        index:
          type: "IVF_FLAT"
          params:
            nlist: 128
        search:
          type: "L2"
          params:
            nprobe: 5

  houseKeeper:
    enabled: true
    beatCadence: 10
    keepFor: 14400
    liveness:
      enabled: false
      keepFor: 31536000
    search:
      enabled: false
      keepFor: 31536000