Deployment

The Biometric Identification Service runs on the integrator's own infrastructure – on-premises or in the customer's cloud – in single- or multi-tenant configurations. Innovatrics neither hosts nor processes the data.

Deployment methods

The service is distributed as Docker images and can be run with a variety of Docker orchestrators:

• Docker Compose – the default, for local development and on-premises deployments.

Supported platforms

Platform	Architecture
Linux	x86_64

Prerequisites

• A Customer Portal account – used to download the deployment package, obtain container-registry credentials, and request the license file.
• Docker and Docker Compose.
• An Innovatrics license file (iengine.lic) valid for the target deployment (see Obtain and place the license file below).
• PostgreSQL, RabbitMQ, and SeaweedFS – all included in the provided Docker Compose stack; no separate installation is required for single-server deployments.

Docker Compose deployment

The service ships as a Docker Compose stack that includes the minimum required services – API, detector, extractor, matcher, and liveness – together with all infrastructure dependencies.

1. Obtain the deployment package

Request the deployment package from the Customer Portal, or from sales@innovatrics.com.

The archive contains everything needed to run a deployment with Docker Compose:

• docker-compose.yml – the services for this deployment
• .env – the configuration shared by all services (edit this to configure the deployment)
• dependencies/docker-compose.yml – the bundled dependencies (database, RabbitMQ, S3 storage, vector database)
• run.sh – brings the whole deployment up (dependencies, database migration, S3 bucket, services)
• the template-migration and embedding-sync helper scripts

2. Configure the environment

Set the required values in .env:

# Registry and version (provided with your deployment package / Customer Portal)
REGISTRY=<your-registry>/
SF_VERSION=<version>

# Database
Database__DbEngine=PgSql
ConnectionStrings__CoreDbContext=Server=db;Database=smartface;Username=postgres;Password=Test1234;Trust Server Certificate=true;

# RabbitMQ
RabbitMQ__Hostname=rmq
RabbitMQ__Username=guest
RabbitMQ__Password=guest
RabbitMQ__Port=5672

# Blob storage (SeaweedFS)
S3Bucket__Endpoint=http://seaweedfs:8333
S3Bucket__BucketName=inno-smartface
S3Bucket__AccessKey=admin
S3Bucket__SecretKey=admin

The database, RabbitMQ, and blob-storage values above are example defaults for a single-server setup. Change all credentials before any production deployment.

3. Log in to the container registry

docker login <registry> -u <username> -p <password>

The registry URL and credentials are available in the Customer Portal.

4. Obtain and place the license file

The license is tied to the host it runs on, so you first read the machine's Hardware ID, then generate a license file for it in the Customer Portal.

1. Read the Hardware ID. Run the license-manager image on the target host (you are already logged in to the registry from step 3):

docker run ${REGISTRY}license-manager:<version>

On ARM hosts, add --privileged:

docker run --privileged ${REGISTRY}license-manager:<version>

It prints:

Hardware ID of this device is: <hardwareID>

2. Generate the license. In the Customer Portal, open Licenses → Generate License, enter the Hardware ID, select the product, and submit. Download the resulting iengine.lic. You can also request it from sales@innovatrics.com.

3. Place the license. It must be bind-mounted into each service container. In the default stack it is expected at ./iengine.lic relative to the compose file:

volumes:
  - "./iengine.lic:/etc/innovatrics/iengine.lic"

5. Start the stack

Run ./run.sh. The script starts the dependencies, migrates the database to this version, creates the S3 bucket, and starts the services. Its comments explain each step.

The REST API is available on port 8098 and the GraphQL API on port 8097 once all services are healthy.

Once running, the services can be restarted at any time with docker compose up -d.

GPU acceleration

The GPU images are built on CUDA 12.8, so the host needs an NVIDIA driver of 570.26 or newer (Linux) and the NVIDIA Container Toolkit. Check the installed driver by running nvidia-smi.

To run extraction and liveness on GPU, set the GPU environment variables on the relevant services and add the NVIDIA runtime:

extractor:
  environment:
    - Gpu__GpuEnabled=true
    - Gpu__GpuNeuralRuntime=Tensor
  runtime: nvidia
  volumes:
    - "/var/tmp/innovatrics/tensor-rt:/var/tmp/innovatrics/tensor-rt"
    - "./iengine.lic:/etc/innovatrics/iengine.lic"

Scaling

Each processing service runs on a single core by default. Add replicas to increase throughput. Remove the container_name key when scaling so Docker can auto-name instances.

extractor:
  image: ${REGISTRY}extractor:${SF_VERSION}
  # container_name: SFExtractor   ← remove when scaling
  deploy:
    replicas: 4

Sizing guidelines

These are indicative figures – actual sizing depends on image quality, detection rate, and hardware. Innovatrics provides a sizing document with per-project recommendations.

Scenario	Extractor replicas	Matcher replicas
Low traffic (~20 req/min)	1	1
Medium traffic (~100 req/min)	2–4	1
High traffic (~500 req/min)	8–16	2–4

The extractor is the primary bottleneck in most deployments. The matcher becomes a bottleneck only at very large watchlists (millions of members) – use Milvus in that case.

Milvus (vector database)

Milvus is disabled by default. Enable it for very-large-gallery deployments where the matcher would otherwise become the bottleneck. Milvus configuration is described in your deployment package; contact Innovatrics if you need help sizing it.

Multi-tenancy

Multi-tenant operation requires an external identity provider (OpenID Connect / OAuth2). Configure the API to validate tokens against your authority:

Authentication__UseAuthentication=true
Authentication__Authority=https://your-idp.example.com
Authentication__Audience=identification-service

Each tenant authenticates with their own credentials. Tenant isolation at the data layer is enforced by the service – watchlists and members belonging to one tenant are not visible to others.

Verifying the deployment

1. Check all containers are running: docker compose ps
2. Open http://localhost:8098 – the Swagger UI should load.
3. Enroll a test watchlist member via POST /api/v1/WatchlistMembers/Register.
4. Submit a face image via POST /api/v1/Watchlists/Search and confirm a match is returned.
5. Submit a liveness / spoof check and confirm a liveness score is returned.

See the REST API page for the full endpoint reference.