Getting Started

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Redis (for background job processing)
• Docker & Docker Compose (optional, for containerized deployment)

Installation

1. Clone the Repository

git clone https://github.com/iursevla/open-receipt-ocr.git
cd open-receipt-ocr

2. Install Dependencies

npm install

This installs dependencies for the entire monorepo including:

• server/ - NestJS backend
• client/ - Angular frontend
• packages/ - Shared types and utilities

3. Configure Environment Variables

Copy the example configuration:

cp server/.env.example server/.env

Open server/.env and add your API keys for the OCR providers you want to use. At minimum, you need to set the NODE_ENV:

NODE_ENV=development

# Add API keys for providers you'll use
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
TAB_SCANNER_API_KEY=your_tabscanner_key

See Configuration Guide for detailed instructions on each provider.

4. Start Redis

The application requires Redis for background job processing. Start it locally:

redis-server

Or using Docker:

docker run -d -p 6379:6379 redis:latest

5. Run the Application

Start both the frontend and backend in development mode:

npm run dev

This will:

• Start the Angular frontend on http://localhost:4200
• Start the NestJS backend on http://localhost:3000
• Watch for changes and auto-reload

6. Access the Application

Open your browser and navigate to:

http://localhost:4200

You should see the Open Receipt OCR interface. Try uploading a receipt image!

Basic Workflow

1. Upload a Receipt: Click the upload button or drag-and-drop an image
2. Select OCR Provider: Choose from available providers (based on your configuration)
3. View Results: Once processing completes, view the extracted text
4. Export: Download or copy the OCR results

Using the Headless API

You can also use the platform programmatically via REST API:

# Upload a file for OCR
curl -X POST http://localhost:3000/ocr-jobs/upload \
  -F "file=@receipt.jpg" \
  -F "ocrProvider_0=mistral" \
  -F "jobName=My Receipt"

# Response: { "id": 123 }

# Check job status
curl http://localhost:3000/ocr-jobs/123

# Response includes: id, status, files with OCR results

See API Documentation for full API reference.

Troubleshooting

Port Already in Use

If you get a port already in use error:

# Change the frontend port
npm run dev -- --port 4300

# Or check what's using the port and kill it
lsof -i :4200  # Find process using port 4200
kill -9 <PID>

Redis Connection Failed

Ensure Redis is running:

redis-cli ping
# Should return: PONG

If using Docker:

docker ps | grep redis
# Should show the redis container running

Module Not Found Errors

Reinstall dependencies:

rm -rf node_modules
npm install

OCR Provider Not Available

Make sure you’ve:

1. Set the required API key in server/.env
2. Restarted the application after adding the key
3. Checked that the provider is properly configured

Next Steps

• Read Configuration Guide to set up OCR providers
• Check Development Guide if you plan to contribute
• Review Extending Guide to add custom providers
• Deploy with Docker Compose