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. If you use your own TSL certs, place them in |
|
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. |
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.
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_PROCESS_RESULTS_LOG_FILE | "false" | controls whether to save the process requests and results to a file |
FACEAPI_PROCESS_RESULTS_LOG_PATH | "logs/process" | specifies the custom folder to save the processing results. The final output is two files(with _in and _out suffixes), located in endpoint/yyyy/mm/dd/hh folder under specified in this property path |
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. |
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
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 |
Identification
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 distance 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 |
Note
To use identification module, you need to specify additional settings such as SQL, Storage, and Milvus.
SQL
The 1:N identification module and liveness module require an sql database to operate. Currently, only the PostgreSQL
database system is supported. A database can be specified (recommended way) as a single URL string or a set of options.
Option | Default | Description |
---|---|---|
FACEAPI_SQL_URL | "postgresql://regula:Regulapasswd#1@127.0.0.1:5432/regula_db" | Connection String to the Postgres database. The form of the URL is dialect://user:password@host/dbname[?key=value..] |
FACEAPI_SQL_DIALECT | "postgresql" | dialect is a database type such as mysql , postgresql or sqlite |
FACEAPI_SQL_HOST | "127.0.0.1:5432" | database host and port |
FACEAPI_SQL_DB | "regula_db" | database name |
FACEAPI_SQL_USER | "regula" | database user |
FACEAPI_SQL_PASSWORD | "Regulapasswd#1" | database user password |
Storage
The 1:N identification module and liveness module require S3 compatible object storage.
Option | Default | Description |
---|---|---|
FACEAPI_STORAGE_ENDPOINT | "https://s3.amazonaws.com or http://localhost:9000" | Endpoint to the S3 storage |
FACEAPI_STORAGE_ACCESS_KEY | "minioadmin" | S3 Access Key |
FACEAPI_STORAGE_SECRET_KEY | "minioadmin" | S3 Access Secret |
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_REGION | "us-east-1" | Storage Region in case of Amazon S3 usage |
Note
If you want to use Full Fuctioanlity of our FaceAPI web service, you should specify both variables - FACEAPI_STORAGE_PERSON_BUCKET_NAME and FACEAPI_STORAGE_SESSION_BUCKET_NAME.
Milvus
The 1:N 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 |