Settings

Overview

The web service is configured via env variables. All relative paths below are sub-paths for the installation folder or the /app/ folder for docker. Let's call it the app root folder.

To make configuration a bit easier, use the .env file. The .env file is located under the app root folder. This file is a text file containing key-value pairs of all the settings required by your application. Using the .env file will enable you to set environment variables for the web service without polluting the global environment namespace.

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

set as an environment variable.
set in .env file.
built in defaults.

Warning

On some systems, files beginning with a dot are hidden by default. Thus, the .env file can't be seen using the standard file viewers or `ls` like commands.

General

Option	Default	Description
FACEAPI_BIND	0.0.0.0:41101	IpAddress:port server binding
FACEAPI_WORKERS	1	number of workers to process requests
FACEAPI_BACKLOG	WORKERS x 15	maximum number of requests in a queue awaiting processing
FACEAPI_TIMEOUT	30	number of seconds for the worker to process the request. Workers that are silent for more than this number of seconds are killed and restarted.
FACEAPI_ENABLE_DEMO_WEB_APP	"true"	serve a demo web app under host root url (ex. localhost:41101/ )
FACEAPI_LIC_URL [docker only]		URL to regula.license file for further download, if the mount option is not available
HTTPS_PROXY		HTTP proxy, used to connect to license service. Do not specify protocol prefix in proxy URL. Instead of `HTTPS_PROXY=http(s)://host:port` use `HTTPS_PROXY=host:port` If you use your own TSL certs, place them in `/etc/ssl/certs` folder in Linux and docker envs.
REGULA_RETURN_SYSTEMINFO	"true"	When set to "false" or 0, there will be no system information returned in the /api/ping response and in the /api/process response.
FACEAPI_TLS_VERSION	1.2	Specifies the version of the TLS (Transport Layer Security) protocol to use for secure connections within the application. String type, accepts the following available versions of TLS: `1.0`, `1.1`, `1.2`, `1.3`.

HTTPS and CORS

Warning

While HTTPS and CORS can be set directly on the web service, we strongly recommend running reverse-proxy in front and moving a configuration to a proxy itself.

Option	Default	Description
FACEAPI_CORS_ORIGINS	no default, that means the web browser will allow requests to the web server from the same domain only	origin, allowed to use API
FACEAPI_CORS_METHODS	all methods	methods, allowed to invoke the API. Specify comma-separated values as single string (ex. "GET,POST,PUT")
FACEAPI_CORS_HEADERS	all headers	headers, allowed to read from the API. Specify comma-separated values as a single string (ex. "content-type,date")

Info

For more details, see a great article about CORS from Mozilla.

Option	Default	Description
FACEAPI_HTTPS	"false"	if enabled, serve the web service via HTTPS using cert and key, specified in the options below
FACEAPI_CERT_FILE	"certs/tls.crt"	specifies a file containing cert file
FACEAPI_KEY_FILE	"certs/tls.key"	specifies a file containing cert key file

Warning

Use the key file without a passphrase. A passphrase causes the web server to crash or infinitely await stdin.

Monitoring

Option	Default	Description
FACEAPI_ENABLE_PROMETHEUS_METRICS	"true" ("false" for Windows)	Whether to enable the option of collecting Prometheus metrics, boolean

Info

Learn about the available Gunicorn metrics on the Monitoring page.

Logging

There are 3 log types in our service:

access logs are just standard HTTP access logs.
application logs are regular application logs, including errors and debug messages.
processing results logs store the processing input and results in the JSON format.

Space-consuming option, up to a few tens of Mb per request. Disabled by default.

Option	Default	Description
FACEAPI_LOGS_ACCESS_CONSOLE	"true"	controls whether to print access logs to a console
FACEAPI_LOGS_ACCESS_FILE	"false"	controls whether to save access logs to a file
FACEAPI_LOGS_ACCESS_FILE_PATH	"logs/access/facesdk-reader-access.log"	specifies the custom file path to save access logs if FACEAPI_LOGS_ACCESS_FILE enabled
FACEAPI_LOGS_APP_CONSOLE	"true"	controls whether to print application logs to a console
FACEAPI_LOGS_APP_FILE	"false"	controls whether to save application logs to a file
FACEAPI_LOGS_APP_FILE_PATH	"logs/app/facesdk-reader-app.log"	specifies the custom file path to save access logs if FACEAPI_LOGS_APP_FILE enabled
FACEAPI_LOGS_LEVEL	"info"	specify application logs level. Possible values: "error", "warn", "info", "debug"
FACEAPI_LOGS_FORMATTER	"text"	possible values: "text"/"json". Some log collectors require logs to be printed in json format.
FACEAPI_PROCESS_RESULTS_LOG_FILE	"false"	deprecated, see FACEAPI_STORAGE_LOGS_DESTINATION below
FACEAPI_PROCESS_RESULTS_LOG_PATH	"logs/process"	deprecated, see FACEAPI_STORAGE_LOGS_DESTINATION below
FACEAPI_STORAGE_LOGS_DESTINATION	not set	Controls whether to save the processing result logs and sets the storage type: `fs` - File System `az` - Azure Blob Storage `gcs` - Google Cloud Storage `s3` - AWS S3 If not set, the processing result logs are not saved.

Access and application logs are printed to stdout.

For access and applications log files, a day-based rotation occurs every midnight UTC. The service keeps the last 30 days of log files.

Liveness Module

Option	Default	Description
FACEAPI_LIVENESS_GEN_2	"false"	specify "true" if you want to enable liveness module
FACEAPI_LIVENESS_HIDE_METADATA	"false"	specify "true" to prevent links to the selfie and video from being added to the GET `/liveness?transactionId=<>` request
FACEAPI_STORAGE_TYPE	"s3"	the storage type for the liveness assessment session information: `fs` - File System `az` - Azure Blob Storage `gcs` - Google Cloud Storage `s3` - AWS S3

Warning

To use the Liveness module, make sure to set the storage and database.

Identification Module

Option	Default	Description
FACEAPI_ENABLE_IDENTIFICATION	"false"	specify "true" if you want to enable 1:N identification module
FACEAPI_MATCHING_INPUT_COUNT_PER_TYPE	"2"	specify a maximum number of matching inputs of each type for matching request
FACEAPI_SEARCH_THRESHOLD	"1.0"	specify 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
FACEAPI_STORAGE_TYPE	"s3"	the storage type for the person's images: `fs` - File System `az` - Azure Blob Storage `gcs` - Google Cloud Storage `s3` - AWS S3

Warning

To use the Identification module, make sure to set the storage, database, and Milvus.

Storage

The supported storage types are:

File System (FS) storage
Azure Blob Storage
Google Cloud Storage
AWS S3

Info

You can find more information about each cloud storage type by navigating the following links: Azure Blob Storage, Google Cloud Storage, AWS S3.

File System (FS)

Note that if you are using Network file storage, you need to mount them as local drives.

For the File System storage, the following environment variables should be used:

Name	Default	Description
FACEAPI_STORAGE_LOGS_DESTINATION	not set	Controls whether to save the processing result logs and sets the storage type: `fs` for File System. If not set, the processing result logs are not saved.
FACEAPI_LOCAL_STORAGE_LOGS_FOLDER	"/app/logs"	The directory path where logs are stored locally.
FACEAPI_LOCAL_STORAGE_PERSON_FOLDER	"faceapi-person"	Folder name where person's images are stored. Specified when using the Identification module.
FACEAPI_LOCAL_STORAGE_SESSION_FOLDER	"faceapi-session"	Folder name where session information is stored. Specified when using the Liveness module.

Note

If you want to use the Full Fuctionality of the FaceAPI web service, you should specify both variables - FACEAPI_LOCAL_STORAGE_PERSON_FOLDER and FACEAPI_LOCAL_STORAGE_SESSION_FOLDER.

Azure Blob Storage

Authentification

To authenticate and access Azure Storage in your application, you can use one of the following authentication methods.

Standard authentication via environment variables: Refer to the official Azure documentation for instructions.
When running in an Azure environment and assigned the appropriate role with Azure Storage access rights, authentication is enabled.

Note

Both methods described above require the StorageAccount to be specified via the FACEAPI_AZURE_STORAGE_ACCOUNT variable.

Alternatively, you can authenticate to Azure Storage using a connection string that shoud be set in the FACEAPI_AZURE_STORAGE_ACCOUNT_CONNECTION_STRING variable. The connection string contains the necessary information to establish a connection to the storage account. Here's an example of a connection string:

FACEAPI_AZURE_STORAGE_ACCOUNT_CONNECTION_STRING="DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=lkschfs7lkfhdyhcbdsk548weksdhc4ksdjvg473239orhfsdjfhsd7kfhfkue/C2RTGHYPui/LPSBnksoMKGw==;BlobEndpoint=http://{hosts['azure']}:10000/devstoreaccount1;"

Make sure to replace {hosts['azure']} in the connection string with the appropriate hostname or IP address of your Azure Storage account.

Info

The connection string can be found in the Access keys section of your Azure Storage account:

Settings

Name	Default	Description
FACEAPI_STORAGE_LOGS_DESTINATION	not set	Controls whether to save the processing result logs and sets the storage type: `az` for Azure Blob Storage. If not set, the processing result logs are not saved.
FACEAPI_STORAGE_TYPE	"s3"	The storage type for the liveness assessment session information (when using the Liveness module) and the person's images (when using the Identification module): `az` for Azure Blob Storage
FACEAPI_AZURE_STORAGE_ACCOUNT		Azure storage account
FACEAPI_AZURE_STORAGE_ACCOUNT_CONNECTION_STRING		Azure storage connection string
FACEAPI_AZURE_STORAGE_PERSON_CONTAINER	"test-faceapi-persons"	Azure storage where person's images are stored. Specified when using the Identification module.
FACEAPI_AZURE_STORAGE_SESSION_CONTAINER	"test-faceapi-session"	Azure storage where session information is stored. Specified when using the Liveness module.
FACEAPI_AZURE_STORAGE_LOGS_CONTAINER	"test-faceapi-logs"	Azure storage where log files are stored

Note

If you want to use the Full Fuctionality of the FaceAPI web service, you should specify both variables - FACEAPI_AZURE_STORAGE_PERSON_CONTAINER and FACEAPI_AZURE_STORAGE_SESSION_CONTAINER.

Google Cloud Storage

To enable, follow the official Google Cloud Storage documentation: https://cloud.google.com/docs/authentication/application-default-credentials.

For the Google Cloud Storage storage, the following environment variables should be used:

Name	Default	Description
FACEAPI_STORAGE_LOGS_DESTINATION	not set	Controls whether to save the processing result logs and sets the storage type: `gcs` for Google Cloud Storage. If not set, the processing result logs are not saved.
FACEAPI_STORAGE_TYPE	"s3"	The storage type for the liveness assessment session information (when using the Liveness module) and the person's images (when using the Identification module): `gcs` for Google Cloud Storage
FACEAPI_STORAGE_LOGS_BUCKET_NAME		Bucket name where log files are stored
FACEAPI_STORAGE_PERSON_BUCKET_NAME	"faceapi-person"	Bucket name where person's images are stored. Specified when using the Identification module.
FACEAPI_STORAGE_SESSION_BUCKET_NAME	"faceapi-session"	Bucket name where session information is stored. Specified when using the Liveness module.

Note

If you want to use the Full Fuctionality of the FaceAPI web service, you should specify both variables - FACEAPI_STORAGE_PERSON_BUCKET_NAME and FACEAPI_STORAGE_SESSION_BUCKET_NAME.

AWS S3

To authenticate and access AWS S3 storage in your application, you can configure it using one of the following methods.

By using the FaceAPI environment variables.
Via the standard AWS envs: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html
By running the application within the AWS environment and assigning the necessary IAM role to your application with the required permissions to access S3.

Note that MinIO storage is utilized for on-premises installations within our containers. It is compatible with AWS S3 and is configured in the same way.

For AWS S3 storage, the following environment variables should be used:

Name	Default	Description
FACEAPI_STORAGE_LOGS_DESTINATION	not set	Controls whether to save the processing result logs and sets the storage type: `s3` for AWS S3. If not set, the processing result logs are not saved.
FACEAPI_STORAGE_TYPE	"s3"	The storage type for the liveness assessment session information (when using the Liveness module) and the person's images (when using the Identification module): `s3` for AWS S3.
FACEAPI_STORAGE_ENDPOINT	"http://minio:9000"	Endpoint to the S3 storage. Note that the variable should be set only if MinIO storage is used.
FACEAPI_STORAGE_REGION	"us-east-1"	Storage Region in case of Amazon S3 usage
FACEAPI_STORAGE_PERSON_BUCKET_NAME	"faceapi-person"	Bucket name where person's images are stored. Specified when using the Identification module.
FACEAPI_STORAGE_SESSION_BUCKET_NAME	"faceapi-session"	Bucket name where session information is stored. Specified when using the Liveness module.
FACEAPI_STORAGE_LOGS_BUCKET_NAME		Bucket name where log files are stored (if using AWS S3 or Google Storage)
FACEAPI_STORAGE_ACCESS_KEY		Deprecated
FACEAPI_STORAGE_SECRET_KEY		Deprecated
FACEAPI_S3_SECURE_CONNECTION	"true"	Whether to check the CA certificate. If set to "false", the certificate is not checked.

Note

If you want to use the Full Fuctionality of the FaceAPI web service, you should specify both variables - FACEAPI_STORAGE_PERSON_BUCKET_NAME and FACEAPI_STORAGE_SESSION_BUCKET_NAME.

Database

The following database types and versions are supported:

PostgreSQL v14 and higher
MariaDB Server v10.7 and higher (and its predecessor MySQL v8 and higher)
Oracle v19c and higher
Sqlite (not recommended for production solutions, not supported on Linux)

Warning

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

CREATE EXTENSION pgcrypto;

The database type is set the following way:

Option	Description
FACEAPI_SQL_URL	The connection string to the database: PostgreSQL `postgresql://regula:Regulapasswd#1@127.0.0.1:5432/regula_db`" MariaDB `mysql+pymysql://root:password@localhost:3306/regula_db` Sqlite `sqlite:///regula_db.sqlite` Oracle `oracle+oracledb://system:admin@localhost:1521/FREE` The form of the URL is `dialect://user:password@host/dbname[?key=value..]`

Milvus

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

Option	Default	Description
FACEAPI_MILVUS_HOST	"127.0.0.1"	Milvus Host Name
FACEAPI_MILVUS_PORT	"19530"	Milvus Port