Face Recognition SDK — Linux / Docker (Fully On-Premise)

🌐 Company Site - Here

🤗 Hugging Face - Here

🛟 Help Center - Here

🐳 Docker Hub - Here

Face Recognition SDK — Linux / Docker (Fully On-Premise)

Introduction

Explore FacePlugin Face Recognition SDK — face detection, quality, template extraction, 1:1 verification and 1:N identification.

This repository is standalone. Pull Docker Hub (no Drive) or download the runtime into this repo and run — no other FacePlugin repository is required.

This is an on-premise FacePlugin SDK. All processing stays on your server — no biometric data is sent to FacePlugin cloud.

One repository for Linux SDK + Docker. The native libraries are linux/amd64; the Docker image runs on Linux, Windows, and macOS hosts via Docker (Apple Silicon uses amd64 emulation).

API server in Docker — test with Postman, curl, or the local Gradio demo (demo.py).

◾ Main Functionalities

Feature	Supported
Face detection	✓
Landmarks / pose / attributes	✓
Template extraction	✓
1:1 verification	✓
1:N identification	✓
Face quality (ICAO)	✓

◾ Product List

Platform	Repository
Android	`FaceRecognition-Android-App`
iOS	`FaceRecognition-iOS-App`
Windows	`FaceRecognition-Windows-App`
Linux / Docker	`FaceRecognition-Linux-App`

Before you start

Step	What you need
1	A Linux host or Docker (Desktop or Engine)
2	Docker Hub pull does not need Drive. Fill `./lib/cpu/` only for Compose / `./run.sh` — see Download runtime libraries
3	You do not need a license to start the API for the first time. Simply launch it without a key, then locate the machine code ( `FPMC1.…`) in the logs or via GET /api/machinecode. Submit this code to FacePlugin(contact) to get activation key ( `FP1.…`) and unlock product endpoints.

You do not need a license to start the API once. Product endpoints unlock after you activate.

System requirements

Item	Minimum	Recommended
CPU	2 cores	8 cores
RAM	4 GB	8 GB
Disk	4 GB	8 GB
OS (Docker)	Linux + Docker Engine	Ubuntu 22.04 / 24.04
OS (local `./run.sh`)	glibc 2.38+ (e.g. Ubuntu 24.04)	Ubuntu 24.04

Start the API

You can start without a license — the server prints your machine code on startup.

The API starts even if activation fails. Copy the machine code (FPMC1.…) from the log and send it to FacePlugin.

Option A — Docker Hub (no Drive download)

Runtime is already inside the image.

sudo docker pull faceplugin/face-recognition:latest
sudo docker run -d --name faceplugin-face-recognition \
  --shm-size=2gb --privileged \
  -p 8083:8083 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/face-recognition:latest
sudo docker logs -f faceplugin-face-recognition
# Look for the machine code line: FPMC1.…

Several containers, one license

On Linux, add -v /etc/machine-id:/etc/machine-id:ro to the docker run above so the machine code stays on that host. Then start another container with a new name and host port — same image, same FP1.… key:

sudo docker run -d --name faceplugin-face-recognition-2 \
  -p 8084:8083 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/face-recognition:latest

Activate on each host port with the same key. On Docker Desktop (macOS/Windows) skip the machine-id volume; each container may need its own license.

Download runtime libraries (lib folder)

Skip this if you used Docker Hub (docker pull / docker run). Runtime is already inside the image.

The ./lib/cpu/ tree is intentionally empty on GitHub because native binaries and model files are too large.

If you are building or running directly from this repository, download the CPU package into ./lib/cpu/. Face Recognition Linux is CPU-only in this version — there is no gpu/ package.

Where to download

FaceRecognition-Linux-App runtime (Google Drive)

How to Download Dependencies into `./lib/cpu/`

Clone the repo (if you have not already):

git clone https://github.com/Faceplugin-ltd/FaceRecognition-Linux-App.git
cd FaceRecognition-Linux-App

Open the Google Drive folder from Where to download.
Download all files in that folder (Drive: select all → Download, or download as a zip).
Put every file directly into ./lib/cpu/ — not inside a nested subfolder.

Correct layout (CPU-only; no gpu/):

FaceRecognition-Linux-App/
└── lib/
    └── cpu/
        ├── libFaceRecognitionSDK.so
        ├── libfar-eng.so
        ├── far.fpk
        └── ... (runtimes from Drive)

Wrong layout: lib/cpu/SomeFolder/libFaceRecognitionSDK.so (a nested folder breaks Docker build and local runs).

Quick check:

ls lib/cpu/libFaceRecognitionSDK.so
ls lib/cpu/libfar-eng.so

If those paths exist, you are ready to start.

Option B — Building locally with Docker Compose

Requires ./lib/cpu/ filled from Drive.

cd FaceRecognition-Linux-App
# macOS/Windows Docker Desktop: remove the /etc/machine-id volume from docker-compose.yml first
sudo docker compose up --build -d
sudo docker compose logs -f
# Look for the machine code line: FPMC1.…
# Detached Compose has no TTY — there is no license prompt. Activate with curl (below).

Option C — Native Linux setup (No Docker)

Requires ./lib/cpu/ filled from Drive.

cd FaceRecognition-Linux-App
./run.sh
# or: python3 app.py
# The machine code (FPMC1.…) is printed in the terminal on startup.

SDK License

Licenses are offline and bound to your app identifier.

How to get a license

Start the server (above) — Docker or local. A license is not required for the first start.
Copy the machine code from the startup log (container logs or the local terminal). It looks like FPMC1.….
Send that machine code to FacePlugin (contact). We will issue an your license key license for that code.
Activate with the license key:

# Paste the FP1. key into ./license.txt (overwrite the file).

# Docker Hub (A) and Compose (B) both expose the API on this host port.
# `docker compose up -d` does not activate — the container is already running
# with no TTY, so it will not re-read license.txt. POST the key instead:
curl -s -X POST http://127.0.0.1:8083/api/activate \
 -H 'Content-Type: text/plain' \
 --data-binary @license.txt

# Compose alternative: after writing license.txt, restart so startup activates:
# sudo docker compose restart

# Local (Option C): stop the process (Ctrl+C), then:
./run.sh

Use the machine code from the environment you will run in production. Docker and local host codes are different — if you run in Docker, send the Docker machine code.

Try it

Health

curl -s http://127.0.0.1:8083/api/health

Documentation

https://doc.faceplugin.com

Postman

Import [postman/FaceRecognition-API.postman_collection.json](postman/FaceRecognition-API.postman_collection.json).

Default base URL: http://127.0.0.1:8083

Canonical protocol: /api/* (see FacePlugin Protocol). No version segment in route paths.

Demo UI (Gradio) — local only

The Docker image is API/SDK server only (no Gradio). For a simple browser test UI on the host (API must already be running on port 8083):

pip3 install -r requirements-demo.txt
DEMO_PORT=9003 API_BASE=http://127.0.0.1:8083 python3 demo.py

Open http://127.0.0.1:9003. Examples when present: assets/examples/samples/.

Tabs: Detect, Quality, Match. Each action has a Result table (attributes, quality checks, or match scores) and Raw JSON. Detect / Quality examples are every file under assets/examples/samples/. Match is Odd vs Even: pick one image from each group, then Match.

About SDK

Use the Python bindings in [sdk.py](sdk.py). Return code 0 means success.

1. Initializing the SDK

Step One

First, obtain the machine code for activation and request a license based on the machine code.

import sdk

machine_code = sdk.get_machine_code()
print("machineCode:", machine_code) # FPMC1.…

Step Two

Next, activate the SDK with the path to your license file (license.txt containing your license key).

ret = sdk.activate("license.txt")

If activation is successful, the return value will be 0. Otherwise, an error value will be returned.

Step Three

After activation, call the initialization function of the SDK.

ret = sdk.init_sdk()

If initialization is successful, the return value will be 0. Otherwise, an error value will be returned.

2. APIs

Detect

result = sdk.detect(base64_image, crop_image=False)

Quality

result = sdk.quality(base64_image, crop_image=False)

Feature

result = sdk.feature(base64_image)

Match

result = sdk.match(base64_image1, base64_image2, crop_image=False)

Similarity

result = sdk.similarity(feature1_b64, feature2_b64)

List of our Products

Contact

Name		Name	Last commit message	Last commit date
assets		assets
lib		lib
postman		postman
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app.py		app.py
build_docker.sh		build_docker.sh
demo.py		demo.py
demo_ui.py		demo_ui.py
docker-compose.yml		docker-compose.yml
license.txt		license.txt
license.txt.example		license.txt.example
license_ux.py		license_ux.py
requirements-demo.txt		requirements-demo.txt
requirements.txt		requirements.txt
run.sh		run.sh
sdk.py		sdk.py

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

🌐 Company Site - Here

🤗 Hugging Face - Here

🛟 Help Center - Here

🐳 Docker Hub - Here

Face Recognition SDK — Linux / Docker (Fully On-Premise)

Introduction

◾ Main Functionalities

◾ Product List

Before you start

System requirements

Start the API

Option A — Docker Hub (no Drive download)

Several containers, one license

Download runtime libraries (lib folder)

Where to download

How to Download Dependencies into ./lib/cpu/

Option B — Building locally with Docker Compose

Option C — Native Linux setup (No Docker)

SDK License

How to get a license

Try it

Health

Documentation

Postman

Demo UI (Gradio) — local only

About SDK

1. Initializing the SDK

Step One

Step Two

Step Three

2. APIs

Detect

Quality

Feature

Match

Similarity

List of our Products

Contact

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

How to Download Dependencies into `./lib/cpu/`