Linux

Faceplugin document verification API for Linux Docker. On-premise passport OCR, MRZ, and authenticity. POST /api/documentProcess on port 8082.

Fully on-premise ID Document Recognition HTTP API for Linux / Docker. Image: faceplugin/document-reader. Default port 8082. Gradio 9002.

Reads ID cards, passports, and driver licenses. OCR, MRZ, barcode / QR, image quality, crops, and optional authenticity (document liveness).

All processing stays on your server. No biometric data is sent to Faceplugin cloud.

--shm-size=2gb is required. A smaller shm size can crash the engine.

Code

GitHub - Faceplugin-ltd/ID-Document-Recognition-Docker: ID Document Recognition & Liveness Detection SDK for Linux & Docker — OCR, MRZ, barcode, document verification, anti-spoofing, and fully on-premise processing.GitHub

Setup

Sizing: Hosting requirements.

1

Pull from Docker Hub (no Google Drive download)

sudo docker pull faceplugin/document-reader:latest
sudo 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

On Docker Desktop omit the /etc/machine-id volume.

2

Confirm health (no license yet)

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

3

Activate

curl -s http://127.0.0.1:8082/api/machinecode
curl -s -X POST http://127.0.0.1:8082/api/activate \
  -H 'Content-Type: text/plain' \
  --data-binary @license.txt

Run multiple containers with one license

You only need this section if you want to run multiple Document Reader containers on the same Linux host.

On Linux, mount /etc/machine-id into each container so they use the same machine code. Each container must have a different container name and host port.

For example:

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 each container with the same license key (POST /api/activate on each host port).

On Docker Desktop (macOS/Windows), omit the /etc/machine-id volume. Each container may require its own license.

Other ways to run

Option B — Docker Compose (local build)

git clone https://github.com/Faceplugin-ltd/ID-Document-Recognition-Docker.git
cd ID-Document-Recognition-Docker

Put the Google Drive runtime files directly in lib/cpu/, then:

# 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

Option C — Native Linux (no Docker)

Same lib/cpu/ layout:

./run.sh

Try online: Hugging Face Space (Gradio UI → your Linux API).

License

Request a License & Support.

Try it

curl -s http://127.0.0.1:8082/api/health
IMG=$(base64 -w0 id-front.jpg)

curl -s -X POST http://127.0.0.1:8082/api/documentProcess \
  -H 'Content-Type: application/json' \
  -d "{\"images\":[{\"image\":\"$IMG\",\"page_idx\":0}],\"response\":{\"OCR\":\"normal\",\"Authenticity\":\"normal\"}}"

Postman: import postman/DocumentReader-API.postman_collection.json from the repo. Base URL http://127.0.0.1:8082.

Gradio (host only):

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. Tabs: Result, Liveness, Images, Raw JSON.

Parse the engine JSON with Document result JSON.

Integrate into your own app

Path	When to use
HTTP	Any language. Keep this API running and POST page images.
sdk.py	Python on the same Linux host as lib/cpu/.

You do not need Gradio in production.

APIs

Endpoint	Purpose
GET /api/health	Process is listening (no license)
GET /api/machinecode	Machine code
GET /api/licenseStatus	License status
GET /api/backend	"cpu"
POST /api/activate	Activate and init_sdk()
POST /api/documentRecognition	OCR / MRZ / barcode / image quality only
POST /api/documentLiveness	Authenticity only
POST /api/documentProcess	Combined OCR + optional authenticity
POST /api/generalProcess	Single-image general process

Full reference: Document Reader HTTP API. Shared control routes: Shared endpoints.

Some routes wrap the result in a small JSON object (an envelope). Process POSTs return engine JSON as the body. Authenticity-only without OCR: ID Document Liveness Linux SDK.

Python:

import sdk

sdk.activate("license.txt")
sdk.init_sdk()
print(sdk.document_recognition([{"image": base64_front}]))
print(sdk.document_process(images, options={"response": {"OCR": "normal", "Authenticity": "normal"}}))

Request a License & Support · Contact us

FAQ

Document verification API? POST /api/documentRecognition / documentProcess on port 8082.

Passport OCR? Yes — OCR, MRZ, barcode, crops in the same JSON.

Related documentation

• Faceplugin ID Document Recognition Server SDK · Windows · Glossary

• Face Recognition Linux SDK

• Face Liveness Detection Linux SDK

• ID Document Liveness Linux SDK

• Document result JSON

• Request a License · Status codes

• Combining products (eKYC) · SDK comparison