ocrbase

PDF ->.MD/.JSON Document OCR and structured data extraction API server backend.

Source

Self-Hosting OCRBase

Complete guide for deploying OCRBase on your own infrastructure.

Prerequisites

PaddleOCR-VL Setup

OCRBase requires a running PaddleOCR-VL service. You can either use a hosted service or self-host it.

Option 1: Self-Host with Docker Compose (Recommended)

Requirements: NVIDIA GPU with CUDA 12.6+, Docker 19.03+

  1. Download the deployment files from PaddleOCR GitHub:
  1. Start the service:
docker compose up
  1. Wait for "Application startup complete" - the service will be available at http://localhost:8080

For detailed configuration options, see the official PaddleOCR-VL documentation.

Option 2: Use a Hosted Service

Set the PADDLE_OCR_URL environment variable to point to your hosted PaddleOCR instance.

Quick Start

# Clone and install
git clone https://github.com/majcheradam/ocrbase
cd ocrbase
bun install

# Start infrastructure
docker compose up -d postgres redis minio paddleocr

# Setup database
bun run db:push

# Start API server + worker
bun run dev

The API will be available at http://localhost:3000.

Environment Variables

Create a .env file in the root directory:

# Required
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ocrbase
BETTER_AUTH_SECRET=your-secret-key-at-least-32-characters-long
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3001

# Redis
REDIS_URL=redis://localhost:6379

# S3/MinIO Storage
S3_ENDPOINT=http://localhost:9000
S3_REGION=us-east-1
S3_BUCKET=ocrbase
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin

# OCR Service
PADDLE_OCR_URL=http://localhost:8080

# Optional - LLM for data extraction
OPENROUTER_API_KEY=your-openrouter-api-key

# Optional - GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Docker Deployment

For production, use Docker Compose:

docker compose up --build

API Reference

REST Endpoints

Method Endpoint Description
GET /health/live Liveness check
GET /health/ready Readiness check
POST /api/jobs Create OCR job
GET /api/jobs List jobs
GET /api/jobs/:id Get job
DELETE /api/jobs/:id Delete job
GET /api/jobs/:id/download Download result
POST /api/schemas Create schema
GET /api/schemas List schemas
GET /api/schemas/:id Get schema
PATCH /api/schemas/:id Update schema
DELETE /api/schemas/:id Delete schema
POST /api/schemas/generate AI-generate schema

WebSocket

WS /ws/jobs/:jobId

Real-time job status updates. See SDK for type-safe usage.

OpenAPI

Interactive documentation at: http://localhost:3000/openapi

Project Structure

ocrbase/
├── apps/
│   ├── web/                 # Frontend (TanStack Start)
│   └── server/              # Backend API (Elysia)
│       ├── src/
│       │   ├── modules/     # Feature modules (jobs, schemas, health)
│       │   ├── plugins/     # Elysia plugins
│       │   ├── services/    # Core services (OCR, LLM, storage)
│       │   └── workers/     # Background job processors
├── packages/
│   ├── sdk/                 # TypeScript SDK (@ocrbase/sdk)
│   ├── auth/                # Authentication (Better-Auth)
│   ├── db/                  # Database schema (Drizzle)
│   ├── env/                 # Environment validation
│   └── paddleocr-vl-ts/     # PaddleOCR client
└── docker-compose.yml

Scripts

Command Description
bun run dev Start all services
bun run dev:server Start API only
bun run dev:web Start frontend only
bun run build Build all packages
bun run check-types TypeScript checking
bun run db:push Push schema to DB
bun run db:studio Open Drizzle Studio
bun run db:migrate Run migrations

Tech Stack

Layer Technology
Runtime Bun
API Framework Elysia
SDK Eden Treaty
Database PostgreSQL + Drizzle ORM
Queue Redis + BullMQ
Storage S3/MinIO
OCR PaddleOCR
Auth Better-Auth
Build Turborepo

Tags: backend   container   ocr   document   pdf  

Last modified 17 February 2026