Settings
Overview
The Document Reader 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 |
|---|---|---|
| DOCREADER_BIND | 0.0.0.0:8080 | IpAddress:port server binding |
| DOCREADER_WORKERS | 1 | number of workers to process requests |
| DOCREADER_BACKLOG | WORKERS x 15 | maximum number of requests in a queue awaiting processing |
| DOCREADER_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. |
| DOCREADER_ENABLE_DEMO_WEB_APP | "true" | serve a demo web app under host root url (ex. localhost:8080/ ) |
| DOCREADER_ROUTING_PREFIX | add a url prefix to all endpoints (ex. localhost:8080/{prefix}/ ) | |
| DOCREADER_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 the license service. Do not specify protocol prefix in proxy URL. Do not specify protocol prefix in proxy URL. Instead If you use your own TLS certs, place them in |
|
| DOCREADER_CONFIG_PATH | "/path/to/config.yaml" | specify the path to the application config file |
| 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 configuration to proxy itself.
| Option | Default | Description |
|---|---|---|
| DOCREADER_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 |
| DOCREADER_CORS_METHODS | all methods | methods, allowed to invoke on the API. Specify comma-separated values as single string (ex. "GET,POST,PUT") |
| DOCREADER_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 |
|---|---|---|
| DOCREADER_HTTPS | "false" | if enabled, serve web service via HTTPS using default cert and key file paths, specified in options below |
| DOCREADER_CERT_FILE | "certs/tls.crt" | specifies the custom file path containing cert file |
| DOCREADER_KEY_FILE | "certs/tls.key" | specifies the custom file path containing key file |
| DOCREADER_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. |
Warning
Use key file without passphrase. 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.
-
document process results logs store document 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 |
|---|---|---|
| DOCREADER_LOGS_ACCESS_CONSOLE | "true" | controls whether to print access logs to a console |
| DOCREADER_LOGS_ACCESS_FILE | "false" | controls whether to save access logs to a file |
| DOCREADER_LOGS_ACCESS_FILE_PATH | "logs/access/document-reader-access.log" | specifies the custom file path to save access logs if DOCREADER_LOGS_ACCESS_FILE enabled |
| DOCREADER_LOGS_APP_CONSOLE | "true" | controls whether to print application logs to a console |
| DOCREADER_LOGS_APP_FILE | "false" | controls whether to save application logs to a file |
| DOCREADER_LOGS_APP_FILE_PATH | "logs/app/document-reader-app.log" | specifies the custom file path to save access logs if DOCREADER_LOGS_APP_FILE enabled |
| DOCREADER_PROCESS_RESULTS_LOG_FILE | "false" | controls whether to save the document process requests and results to a file |
| DOCREADER_PROCESS_RESULTS_LOG_PATH | "logs/process" | specifies the custom folder to save the document process requests and results if DOCREADER_PROCESS_RESULTS_LOG_FILE enabled. The final output is a zip file, located in the yyyy/mm/dd/hh folder under the specified in this property root path. |
| DOCREADER_LOGS_PROCESS_SAVE_RESULT | "true" | if false, only the document process requests are saved, the result is not. |
| DOCREADER_LOGS_LEVEL | "info" | specify application logs level. Possible values: "error", "warn", "info", "debug". |
| DOCREADER_LOGS_FORMATTER | "text" | possible values: "text"/"json". Some log collectors require logs to be printed in json format. |
The access and application logs are printed to stdout.
For the access and applications log files, a day-based rotation occurs every midnight UTC. The service keeps the last 30 days of log files.
Chip Verification
| Option | Default | Description |
|---|---|---|
| REGULA_SERVER_SIDE_CHIP_VERIFICATION | "false" | controls whether to enable server side chip verification |
| REGULA_STORAGE_URL | "null" | S3 object storage endpoint |
| REGULA_STORAGE_ACCESS_KEY | "null" | S3 object storage Access Key |
| REGULA_STORAGE_SECRET_KEY | "null" | S3 object storage Secret Key |
| REGULA_STORAGE_CHIP_DATA_BUCKET | "null" | specify the custom bucket to store CA keys and AA challenges |
| REGULA_STORAGE_REGION | "null" | specify a region for AWS, for example "eu-central-1" |
| REGULA_STORAGE_CLIENT_TYPE | "null" | specify the client type, the available values are "AWS" and "Minio" |
Application
| Option | Default | Description |
|---|---|---|
| RFID_PKD_PA | "false" | controls whether to enable the RFID PA feature |
| RFID_PKD_PA_PATH | "rfid_pkd" | specify the custom folder prepopulated with masterlists for RFID PKD |
Face API Integration
Learn more about Face SDK Integration
| Option | Default | Description |
|---|---|---|
| REGULA_USEFACEAPI | false | Whether to use Face SDK in each request, boolean. |
| REGULA_FACEAPI_URL | "https://faceapi.regulaforensics.com" | The URL of the Regula Face SDK service instance to be used. Note that the default https://faceapi.regulaforensics.com can be used for demo purposes only. For production use, you should purchase an appropriate license. Please contact us here. |
| REGULA_FACEAPI_MODE | "match" | The processing mode: "match" or "match+search". match is a comparison of persons that are passed in the request, works by default. match+search performs both matching and searching by image. If only one person is available, match is not performed and only the search is carried out. If no search parameters are specified, the search is conducted over the entire database with the default parameters. Learn more in OpenAPI documentation |
| REGULA_FACEAPI_SEARCH | not set | The search filter that can be applied if the "match+search" mode is enabled. May include limit, threshold, group_ids. If the group_ids are specified, the search is performed only in these groups. Find more information in the OpenAPI documentation. |
| REGULA_FACEAPI_THRESHOLD | "75" | The similarity threshold, 0-100. Above 75 means that the faces' similarity is verified, below 75 is not. |
| REGULA_FACEAPI_SERVICETIMEOUT | "3000" | The service request timeout, ms. |
| REGULA_FACEAPI_PROXY | not set | Proxy to use, should be set according to the cURL standart. |
| REGULA_FACEAPI_PROXY_USERPWD | not set | Username and password to use for proxy authentication, should be set according to the cURL standart. |
| REGULA_FACEAPI_PROXY_TYPE | not set | Proxy protocol type, should be set according to the cURL standart. |
| REGULA_FACEAPI_CHILDAGETHRESHOLD | 13 | The minimum age of a child at which photo comparison is initiated. |
| REGULA_FACEAPI_CHILDDOCVALIDITYYEARS | 5 | The assumed duration of validity for a child's passport, years. |