Skip to content

Getting Started

Important information to get started with the Face SDK.

Worker Model

By default, the web service starts with one worker. Each worker processes requests in a single-threaded mode that means that it can process only one request at a time. So, if you submit many requests at once, they queue up and are processed one by one.

To improve the throughput performance, you can launch more workers according to the planned load. The web service can spawn multiple workers under one service instance. You may set the workers number based on the hardware limitation you have.

Also, you can use N web server instances with multiple workers under the load balancer to increase the performance even more.


Each worker in our license model counts as an instance. So, a setup of 3 machines with 2 workers on each requires a license with 6 instances.

For transaction-based licenses, the number of workers is not limited, only the number of the process requests counts.

Interactions with Licensing Service

When working with an online license, the web service contacts the licensing service at via encrypted communication and sends requests for validation.


The licensing service is created to manage the license keys, and this is its only purpose. The web service is customer-hosted, on-prem, and all personal data remains on the customer's servers and is not being communicated back to Regula.

On the start of a worker, the licensing service is contacted, and a registration request is sent. If the license is valid, the worker runs. Otherwise, it fails.

In case the online license is transaction-based, each time the functionality is used, the web service contacts the licensing service with a POST request. This request consists of the license id, transaction id, session id, client ip, transaction scenario, product type and version used, and the timestamp. If the license is valid for this kind of request, the request gets logged, the 'OK' response is provided, and the SDK returns the processing results.

In case the online license is instance/worker-based, heartbeats are monitored instead. Every hour the web service sends a heartbeat request to the licensing service providing the following information: license id, session id, client ip, product type and version used, and the timestamp. If the license is valid and the response is 'OK', the web service continues to perform. If the response is 'FAIL', the Error message appears.

Heartbeats continue and as soon as the license becomes valid again, the operation of the web service restores automatically. In case there is no Internet connection when the request is sent, the result is 'TIMEOUT'.

Connect to Licensing Service via HTTP Proxy

If you host the SDK in an isolated private environment, you can specify an HTTP proxy via the HTTPS_PROXY env variable. The proxy will be used by the web service to connect to the licensing service.


Do not specify any protocol prefix in the 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 the /etc/ssl/certs folder in Linux and docker envs.

Proxy Guard

The Regula Face SDK is not a general HTTP web server that handles hundreds of requests per second. Typical processing takes up to a few seconds, so we can call it CPU intensive. Considering that a typical instance has 1-4 workers, we need to carefully manage workers' time.

One of the main sources of wasting worker's processing time is a slow clients problem. When the web service receives a request from a client with a slow internet connection, this request goes to a free worker. The worker will be bottlenecked by the speed of the client connection, and it will be blocked until the slow client finishes sending a large ID image. Being blocked means that this worker process can't handle any other request in the meantime, it’s just there, idle, waiting to receive the entire request, so it can start really processing it.

We strongly recommend using the Face SDK behind a proxy server. Although there are many HTTP proxies available, we strongly advise that you use Nginx. If you choose another proxy server, you need to make sure that it buffers slow clients.


Typical Load Balancers from cloud providers, such as ELB/ALB from aws, do not buffer slow clients. So, you still need to use some proxy server between LB and the Face SDK.


The recommended machine settings are 1CPU and 3Gb RAM per worker.


For using the docker or Linux instances, you will need an online license. Internet connection is a mandatory requirement for an online license, thus the instance with a pre-installed service must have internet access at least to the URL.


The Version A.B.C.D is composed of:

  • A.B for the Regula SDK version
  • C for the neural network version
  • D for the service wrapper version

For example, a version 3.0.310.2 should be interpreted as follows:

  • 3.0 is the Regula SDK version
  • 310 is the current neural network version
  • 2 is the web service wrapper version