Rootoor/doctr-ocr-service

1---2title: DocTR OCR Service3emoji: 🔍4colorFrom: blue5colorTo: green6sdk: docker7pinned: false8---9 10# docTR OCR Service11 12Self-hosted REST microservice for text extraction from images. Used in the **Webhook: Verify Student Card** workflow.13 14Based on [docTR](https://github.com/mindee/doctr) (Apache 2.0) — no data sent to any external service.15 16## Requirements17 18- Docker19- Docker Compose v2 (`docker compose`, not `docker-compose`)20 21## Setup22 23```bash24cp .env.example .env25# Edit .env: set API_KEY to a strong secret26docker compose up -d --build27```28 29The first start downloads docTR models (~130 MB) and caches them in a persistent Docker volume. Subsequent restarts are fast.30 31## Endpoints32 33### `GET /health`34 35Returns service status. No auth required.36 37```bash38curl http://localhost:8001/health39```40 41```json42{ "ok": true, "message": "OCR service is running", "data": {} }43```44 45---46 47### `POST /extract/student-card`48 49Main endpoint for the student card verification workflow. Extracts the student number and academic year from a card photo.50 51Handles automatically:52- **Any orientation** (portrait, landscape, 90°, 270°) — tries 4 rotations53- **EXIF correction** — compensates for phone orientation metadata54- **Blur detection** — rejects unreadable photos before OCR processing55 56**Body**: `multipart/form-data` with a `file` field (JPEG, PNG, or WebP). Max 10 MB.57 58```bash59curl -X POST http://localhost:8001/extract/student-card \60  -F "file=@/path/to/card.jpg"61```62 63**Success response**:64```json65{66  "ok": true,67  "message": "Carte lue avec succès",68  "data": {69    "student_number": "645102",70    "academic_year": "2024-2025"71  }72}73```74 75**Blurry photo**:76```json77{78  "ok": false,79  "message": "Photo trop floue",80  "data": {81    "error": "La photo est trop floue pour être lue. Prends une photo plus nette, bien éclairée et sans bouger.",82    "traceback": null83  }84}85```86 87**Unreadable card** (sharp photo but fields not found):88```json89{90  "ok": false,91  "message": "Carte illisible",92  "data": {93    "error": "Impossible d'extraire le numéro étudiant ou l'année académique. Envoie une photo plus nette de ta carte.",94    "traceback": null95  }96}97```98 99---100 101### `POST /extract`102 103Extracts raw text from any image. Requires `X-API-Key` header if `API_KEY` is set.104 105**Body**: `multipart/form-data` with a `file` field (JPEG, PNG, or WebP). Max 10 MB.106 107```bash108curl -X POST http://localhost:8001/extract \109  -H "X-API-Key: your_api_key" \110  -F "file=@/path/to/image.jpg"111```112 113**Success response**:114```json115{116  "ok": true,117  "message": "Text extracted successfully",118  "data": {119    "full_text": "UNIVERSITE DE LOME\nNuméro: 645102\n...",120    "blocks": ["block 1", "block 2"],121    "page_count": 1122  }123}124```125 126## Configuration127 128| Variable | Default | Description |129|---|---|---|130| `PORT` | `8001` | Host port the service listens on |131| `API_KEY` | *(empty)* | Required `X-API-Key` header value. Leave empty to disable auth |132 133## EC2 Deployment134 135### Prerequisites136 137Ensure the EC2 instance has a swap file (critical on 2 GB RAM instances):138 139```bash140sudo fallocate -l 4G /swapfile141sudo chmod 600 /swapfile142sudo mkswap /swapfile143sudo swapon /swapfile144echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab145```146 147### Start the service148 149```bash150cp .env.example .env151# Set a strong API_KEY in .env152docker compose up -d153```154 155The service binds to `127.0.0.1:8001` only — it is not directly reachable from the internet.156 157### Nginx configuration158 159Add the following to your existing Nginx config (inside the appropriate `server` block):160 161```nginx162location /ocr/ {163    proxy_pass http://127.0.0.1:8001/;164    proxy_set_header Host $host;165    proxy_set_header X-Real-IP $remote_addr;166    client_max_body_size 10m;167    proxy_read_timeout 120s;168}169```170 171Then reload Nginx:172 173```bash174sudo nginx -t && sudo systemctl reload nginx175```176 177## Management178 179```bash180# Start181docker compose up -d182 183# Stop184docker compose down185 186# Logs187docker logs doctr-ocr -f188 189# Rebuild after code changes190docker compose up -d --build191```192 193## Structure194 195```196doctr/197├── app/198│   ├── main.py           # FastAPI app199│   └── requirements.txt  # Python dependencies200├── Dockerfile201├── docker-compose.yml202├── .env.example203└── README.md204```205 206## Notes207 208- Models are cached in the `doctr_models` Docker volume — they survive restarts.209- Uses **PyTorch CPU** backend (no GPU required).210- Memory capped at 1400 MB in docker-compose to protect the host.211- Uses `docker compose` (v2) — `docker-compose` (v1) is not supported.212- Student number accepted: 5–7 digits, anchored to the `Numéro:` label on the card.213