faceplugin/document-reader repository overview

⁠FacePlugin Document Reader

On-premise ID / passport / document OCR and MRZ HTTP API. Linux amd64. Official image: faceplugin/document-reader⁠.

The image is an API/SDK server only (no Gradio). Runtime libraries are already inside — no Google Drive download is required to pull and run.

• Company: faceplugin.com⁠
• Docs: doc.faceplugin.com⁠
• GitHub: Faceplugin-ltd/DocumentReader-Linux-App⁠
• Contact: [email protected]⁠ · WhatsApp +1 469 278 4822⁠

⁠Tags

docker pull faceplugin/document-reader:latest

⁠Quick start

Default listen port 8082. Use --shm-size=2gb (the SDK unpacks models into /dev/shm; Docker’s 64MB default is too small).

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

docker logs -f faceplugin-document-reader
# Look for the machine code line: FPMC1.…

API: http://127.0.0.1:8082

macOS / Windows Docker Desktop: omit -v /etc/machine-id:/etc/machine-id:ro (there is no host /etc/machine-id). Each container may get a different machine code.

⁠License

The published image does not include a license. The API starts without one and prints a machine code (FPMC1.…). Product endpoints unlock after you activate.

1. Copy the machine code from logs, or GET /api/machinecode.
2. Send that code to FacePlugin. You receive a license key (FP1.…).
3. Activate:

# Paste the FP1. key into license.txt, then:
curl -s -X POST http://127.0.0.1:8082/api/activate \
  -H 'Content-Type: text/plain' \
  --data-binary @license.txt

Docker and native-host codes are different. If you run in Docker, send the Docker machine code.

⁠Several containers, one license

On Linux, keep the machine-id mount so extra containers on the same host share one fingerprint. Use a new name and host port:

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 published port with the same key. Without the machine-id volume (typical Docker Desktop), codes can differ.

⁠API (after activation)

Health:

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

Postman collection and native (non-Docker) setup: DocumentReader-Linux-App⁠.