Quickstart

1. Get the models

The service needs two ONNX models: a face detector and a face embedder. Fetch both with the provided script:

./scripts/download_models.sh

This downloads:

File	Source	License
`models/face_detection_yunet.onnx`	OpenCV Zoo	Apache-2.0
`models/arcface_w600k_r50.onnx`	InsightFace `buffalo_l`	MIT

Both files land in ./models/. This directory is git-ignored — models are fetched at build/deploy time, not committed. Do this before docker build — the Docker image bakes these files in (see the Docker tab below), so an empty models/ produces a broken image.

See Models for exactly what these models expect as input, why these specific ones were chosen, and what got ruled out along the way.

2. Choose a build path

Docker (recommended)
Local build

No local toolchain needed — everything (Drogon, OpenCV, ONNX Runtime) builds inside the image, and the models are baked in too, so the resulting image is a single, self-contained, plug-and-play artifact — push it to any cloud host and just start the container:

docker build -t face-engine .
docker run -p 8080:8080 face-engine

No volume mount, no separate model-fetch step on the target host. Prefer a smaller, model-agnostic image instead (e.g. to swap models without a rebuild)? See Deployment → Baking in models for the one-line change to mount them at runtime instead.

The builder stage compiles OpenCV ≥ 4.8 from source rather than using Ubuntu 24.04’s apt-packaged 4.6.0. The YuNet detector model requires 4.8+ to run at all — older versions fail at runtime, not build time, with Layer with requested id=-1 not found (opencv_zoo#172). This means docker build takes a while (a full OpenCV compile) — that’s expected, not a hang. See Deployment for the full breakdown.

Faster iteration once your toolchain is set up, but you own the dependency versions.Requires:

CMake ≥ 3.16
A C++17 compiler
OpenCV ≥ 4.8 dev headers (macOS Homebrew’s OpenCV 5.x works; see the version-gated include in FaceAligner.h if you hit a estimateAffinePartial2D/boundingRect compile error)
Drogon built from source (not packaged at a recent-enough version on most distros — see the Dockerfile’s builder stage for the exact clone/build/install commands)
An extracted ONNX Runtime release matching your OS/arch

cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DONNXRUNTIME_ROOT=/path/to/onnxruntime
cmake --build build -j

DETECTOR_MODEL_PATH=./models/face_detection_yunet.onnx \
EMBEDDER_MODEL_PATH=./models/arcface_w600k_r50.onnx \
./build/face_engine

On macOS, the ONNX Runtime shared library uses @rpath — you’ll need DYLD_LIBRARY_PATH=/path/to/onnxruntime/lib set when running the binary directly (not needed in Docker; the Dockerfile copies the library to /usr/local/lib and runs ldconfig).

3. Confirm it’s up

curl http://localhost:8080/v1/ready
# {"ready":true}

If this returns 503 instead, the models are still loading — see Health & Readiness.

4. Try it

curl -X POST http://localhost:8080/v1/embed -F "image=@face1.jpg"

curl -X POST http://localhost:8080/v1/compare \
    -F "image1=@face1.jpg" -F "image2=@face2.jpg"

Full request/response contracts are in the API Reference.

Getting Started

Architecture

Deployment

Testing & Validation

Security

API Reference

1. Get the models

2. Choose a build path

3. Confirm it’s up

4. Try it

​1. Get the models

​2. Choose a build path

​3. Confirm it’s up

​4. Try it

1. Get the models

2. Choose a build path

3. Confirm it’s up

4. Try it