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

🌐 Company Site - Here

🤗 Hugging Face - Here

🛟 Help Center - Here

🐳 Docker Hub - Here

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

Ready in ~10 minutes (after Drive download or Docker Hub pull): Fastest: docker pull faceplugin/document-reader:latest → run → copy FPMC1.… → activate. From source: put files in lib/cpu/ → ./run.sh → Postman / python3 demo.py. Jump: Start the API · Download runtime · About SDK

Introduction

Explore FacePlugin Document Reader SDK — ID cards, passports, driver licenses with OCR, MRZ, barcode and optional NFC/RFID.

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

Standalone repository — pull Docker Hub (no Drive) or clone this repo, fill lib/cpu/ from Google Drive, and run. No other FacePlugin repository is required.

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
ID Card / Passport / Driver License	✓
MRZ / Barcode / QR / OCR	✓
Document detection & classification	✓
Auto-capture & image quality	✓
Face extraction from document	✓
NFC / RFID (where available)	✓

◾ Product List

Platform	Repository
Android	`DocumentReader-Android-App`
iOS	`DocumentReader-iOS-App`
Windows	`DocumentReader-Windows-App`
Linux / Docker	`ID-Document-Recognition`

ID-Document-Recognition is one repository: Linux SDK runtime + Docker image (same tree).

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	Ubuntu 20.04+ (x86_64)	Ubuntu 22.04 / 24.04
GPU (optional)	—	— (CPU-only product)

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/document-reader:latest
docker run -d --name faceplugin-document-reader \
  --shm-size=2gb --privileged \
  -p 8082:8082 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/document-reader:latest
sudo docker logs -f faceplugin-document-reader
# 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-document-reader-2 \
  --shm-size=2gb --privileged \
  -p 8083:8082 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/document-reader: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/ 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/. DocumentReader is CPU-only — there is no gpu/ package.

Where to download

DocumentReader-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/ID-Document-Recognition.git
cd ID-Document-Recognition

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 into ./lib/cpu/ — not inside a nested subfolder under cpu/.

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

ID-Document-Recognition/
└── lib/
 └── cpu/
 ├── libDocSDK.so
 ├── libDocumentEngine.so
 ├── dcr.fpk
 └── .. (other files from Drive)

Wrong layout: lib/cpu/SomeFolder/libDocSDK.so (an extra nested folder breaks Docker build and local runs).

Quick check:

ls lib/cpu/libDocSDK.so
ls lib/cpu/libDocumentEngine.so
ls lib/cpu/dcr.fpk

If those paths exist, you are ready to start.

Option B — Building locally with Docker Compose

Requires ./lib/cpu/ filled from Drive.

cd ID-Document-Recognition
# 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 ID-Document-Recognition
./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:8082/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:8082/api/health

Documentation

https://doc.faceplugin.com

Postman

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

Default base URL: http://127.0.0.1:8082

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 8082):

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

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

The Result tab shows document status plus an extracted-field table (OCR / MRZ / Barcode). The Images tab shows portrait / signature / cropped pages from the API. The Raw JSON tab shows the full API response.

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

Document process

result = sdk.document_process(
 [{"image": base64_front}],
 rfid="",
 options={"response": {"OCR": "normal", "MRZ": "normal", "Barcode": "normal"}},
)

# Front + back (two images)
result = sdk.document_process(
 [
 {"image": base64_front, "page_idx": 0},
 {"image": base64_back, "page_idx": 1},
 ],
 rfid="",
 options={"response": {"OCR": "normal", "MRZ": "normal", "Barcode": "normal"}},
)

Optional session APIs (same opcodes as Android): sdk.start_new_session(), sdk.start_new_page(), sdk.unload().

General process

result = sdk.general_process(base64_image, options={})

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

ID Document 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

Document process

General process

List of our Products

Contact

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

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