Environment Variables Configuration (Deprecated)
Warning
Starting from the 7.1 Document Reader SDK release, the conventional configuration via environment variables is deprecated in most cases. YAML file configuration should be used instead, otherwise the significant part of existing and upcoming features may be unavailable. To transfer your current existing Web Service configuration from environment variables to the YAML format, consult this Migration Guide.
Some functionality of the Document Reader SDK Web Service can still be configured via env variables. All relative paths considered here are sub-paths to the installation folder, or the /app/ folder for docker. Let's call it the app root folder.
To make the configuration a bit easier, you can use the .env file, defining multiple environment variables with their values at the same time. 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 the service. Using the .env file enables you to set environment variables for the web service without cluttering the global environment namespace.
The universal order of precedence for all configuration options is as follows:
- Parameters from the
config.yamlfile - Environment variables from the
.envfile - Environment variables from the OS
- Built-in defaults
Note that in some systems, files beginning with a dot are hidden by default. Thus, the .env file can't be discovered using the standard file viewers or ls-like terminal commands.
See the detailed description of all available Web Service settings that can be set via environment variables.
General Settings
| Setting | Default | Description |
|---|---|---|
| DOCREADER_BIND | 0.0.0.0:8080 |
IpAddress:port server binding |
| DOCREADER_WORKERS | 1 |
Number of workers to process requests. For Windows, 1 is the only option; for other OS, you can set another number, depending on available hardware resources. |
| DOCREADER_TIMEOUT | 30 (for Windows N/A) |
Number of seconds for the worker to process the request. For Windows a timeout is not applied, the parameter's value is ignored. Workers that remain idle for more than this number of seconds are killed and restarted. |
| DOCREADER_ENABLE_DEMO_WEB_APP | "true" |
Whether to serve a demo web app under the host root url (for example localhost:8080/). |
| DOCREADER_ROUTING_PREFIX | — | URL prefix, to be added to all endpoints (for example 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 for connection to the license service in the form If you use your own TLS certs, place them in |
| DOCREADER_CONFIG_PATH | "/path/to/config.yaml" |
Path to the YAML application config file. |
| REGULA_RETURN_SYSTEMINFO | "true" |
Whether to return the system information in the /api/ping and /api/process response. |
| REGULA_LICENSE | — | Specifies the license as a Base64-encoded string. |
HTTPS and CORS
Using environment variables for defining the considered settings has been deprecated since release 7.1. Use YAML file configuration instead.
While HTTPS and CORS can be set directly on the web service, we strongly recommend running a reverse proxy server in front and move configuration to it instead.
| 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 of requests, allowed to use API. |
| DOCREADER_CORS_METHODS | all methods | Methods, allowed to invoke on the API. Comma-separated values as a single string (for example, "GET,POST,PUT"). |
| DOCREADER_CORS_HEADERS | all headers | Headers, allowed to read from the API. Comma-separated values as a single string (for example, "content-type,date"). |
Info
For more details, see the Cross-Origin Resource Sharing (CORS) article from Mozilla.
| Setting | Default | Description |
|---|---|---|
| DOCREADER_HTTPS | "false" |
Whether to provide the Web Service via HTTPS, setting default cert and key file paths, specified in other corresponding environment variables described in the current table. |
| DOCREADER_CERT_FILE | "certs/tls.crt" |
Custom file path containing cert file. |
| DOCREADER_KEY_FILE | "certs/tls.key" |
Custom file path containing key file. |
| DOCREADER_TLS_VERSION | 1.2 |
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.
Monitoring
Windows is not supported.
| Setting | Default | Description |
|---|---|---|
| ENABLE_PROMETHEUS_METRICS | "true" |
Whether to collect Prometheus metrics, boolean. |
| PROMETHEUS_MULTIPROC_DIR | "/tmp/metrics" |
Custom directory to store metrics. |
Logging
The Document Reader SDK Web Service provides three types of logs:
access logsare just the standard HTTP access logs.application logsare the regular application logs, including errors and debug messages.document process results logsstore document processing input and results in the JSON format.
Writing logs into a file, instead of stdout, may consume a significant amount of space (up to several dozen of Mbs). So, the corresponding options are disabled by default. Consider enabling them wisely.
| Setting | Default | Description |
|---|---|---|
| DOCREADER_LOGS_ACCESS_CONSOLE | "true" |
Whether to print access logs to a console. |
| DOCREADER_LOGS_ACCESS_FILE | "false" |
Whether to save access logs to a file. |
| DOCREADER_LOGS_ACCESS_FILE_PATH | "logs/access/document-reader-access.log" |
If DOCREADER_LOGS_ACCESS_FILE enabled, specifies the custom file path to save access logs. |
| DOCREADER_LOGS_APP_CONSOLE | "true" |
Whether to print application logs to a console. |
| DOCREADER_LOGS_APP_FILE | "false" |
Whether to save application logs to a file. |
| DOCREADER_LOGS_APP_FILE_PATH | "logs/app/document-reader-app.log" |
If DOCREADER_LOGS_APP_FILE enabled, specifies the custom file path to save access logs. |
| DOCREADER_PROCESS_RESULTS_LOG_FILE | "false" |
Whether to save the document process requests and results to a file. |
| DOCREADER_PROCESS_RESULTS_LOG_PATH | "logs/process" |
If DOCREADER_PROCESS_RESULTS_LOG_FILE enabled, specifies the custom folder to save the document process logs. The final output is a zip archive, 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" |
Logging level. Possible values: "error", "warn", "info", "debug". |
| DOCREADER_LOGS_FORMATTER | "text" |
Logs format. Possible values: "text"/"json". (Some log collectors require logs in JSON format.) |
By default, 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
| Setting | Default | Description |
|---|---|---|
| REGULA_SERVER_SIDE_CHIP_VERIFICATION | "false" |
Whether to enable the 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" |
Custom bucket to store CA keys and AA challenges. |
| REGULA_STORAGE_REGION | "null" |
Region for AWS, for example "eu-central-1" |
| REGULA_STORAGE_CLIENT_TYPE | "null" |
Client type, possible values: "AWS" and "Minio" |
Application
| Setting | Default | Description |
|---|---|---|
| RFID_PKD_PA | "false" |
Whether to enable the RFID PA feature. |
| RFID_PKD_PA_PATH | "rfid_pkd" |
Custom folder prepopulated with masterlists for RFID PKD. |
Face API Integration
Learn more about Face SDK Integration
| Setting | Default | Description |
|---|---|---|
| REGULA_USEFACEAPI | false |
Whether to use Face SDK in each request, boolean. |
| REGULA_FACEAPI_URL | "https://faceapi.regulaforensics.com" |
URL of Regula Face SDK service instance. Note that the default URL https://faceapi.regulaforensics.com can be used for demo purposes only. For production purposes, you should purchase an appropriate license. For more details, follow the link Face SDK. |
| REGULA_FACEAPI_MODE | "match" |
Processing mode: match or match+search. match is a comparison of persons that are passed in the request, enabled by default. match+search performs both matching and searching by image. If only one person is available, match procedure is skipped and only the search is performed. If no search parameters are specified, the search is conducted over the entire database with the default parameters. For more information, explore the OpenAPI documentation. |
| REGULA_FACEAPI_SEARCH | not set | 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. For more information, explore 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" |
Service request timeout, ms. |
| REGULA_FACEAPI_PROXY | not set | Proxy to use, should be set according to the cURL standard. |
| REGULA_FACEAPI_PROXY_USERPWD | not set | Username and password to use for proxy authentication, should be set in accordance with the cURL standard. |
| REGULA_FACEAPI_PROXY_TYPE | not set | Proxy protocol type, should be set according to the cURL standard. |
| REGULA_FACEAPI_CHILDAGETHRESHOLD | 13 |
Minimum age of a child, at which photo comparison is initiated. |
| REGULA_FACEAPI_CHILDDOCVALIDITYYEARS | 5 |
Estimated duration of validity for a child's passport, years. |