Skip to content

QUICKSTART.md

Latest commit

 

History

History
210 lines (163 loc) · 4.59 KB

QUICKSTART.md

File metadata and controls

210 lines (163 loc) · 4.59 KB

Quick Start Guide

Prerequisites

  • Docker & Docker Compose
  • (Optional) NVIDIA Docker runtime for GPU support

Setup

  1. Initial setup:

    bash scripts/setup_dev.sh

  2. Edit environment variables (if needed):

    nano .env

Running the Application

Development Mode (with GPU)

docker compose --profile app up --build

Access:

CPU-Only Mode

docker compose -f docker-compose.yml -f docker-compose.cpu.yml --profile app up --build

Production Mode

docker compose -f docker-compose.yml -f docker-compose.prod.yml --profile app up -d

# Scale workers
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --scale worker=3

Training Models

# Run OCR training
docker compose --profile training run training python scripts/train_ocr.py --config configs/ocr_baseline.yaml

# Run classifier training
docker compose --profile training run training python scripts/train_classifier.py --config configs/classifier_baseline.yaml

Development Workflow

Backend Development

# Install dependencies locally
cd backend
pip install -e ".[dev]"

# Run tests
pytest

# Run API server locally (without Docker)
uvicorn src.api.main:app --reload

Frontend Development

# Install dependencies
cd frontend
npm install

# Run dev server
npm run dev

# Build for production
npm run build

C Library Development

cd c_library
make clean
make
sudo make install

Useful Commands

View logs

# All services
docker compose --profile app logs -f

# Specific service
docker compose logs -f worker

Stop services

docker compose --profile app down

Rebuild specific service

docker compose --profile app build worker
docker compose --profile app up -d worker

Access container shell

docker exec -it ocr-worker bash

Monitor Celery workers

docker exec -it ocr-worker celery -A src.worker.celery_app inspect active
docker exec -it ocr-worker celery -A src.worker.celery_app inspect stats

API Usage

Submit a job

curl -X POST http://localhost:8000/api/jobs \
  -F "file=@/path/to/image.jpg"

Response:

{
  "job_id": "abc123...",
  "status": "pending"
}

Check job status

curl http://localhost:8000/api/jobs/abc123...

Project Structure Summary

new-project/
├── backend/               # Python backend (API + Worker + ML)
│   ├── src/
│   │   ├── api/          # FastAPI routes and schemas
│   │   ├── worker/       # Celery tasks
│   │   ├── ml/           # ML models and inference
│   │   └── common/       # Shared utilities
│   ├── tests/            # Unit tests
│   └── requirements/     # Python dependencies
│
├── frontend/             # React SPA
│   ├── src/
│   │   ├── api/         # API client
│   │   ├── components/  # React components
│   │   ├── hooks/       # Custom hooks
│   │   └── pages/       # Page components
│   └── nginx.conf       # Nginx configuration
│
├── training/             # Training scripts and configs
│   ├── scripts/         # Training scripts
│   ├── configs/         # Experiment configs
│   └── notebooks/       # Jupyter notebooks
│
├── c_library/            # Custom C library
│   ├── src/             # C source code
│   ├── include/         # Headers
│   └── Makefile         # Build configuration
│
└── docker-compose.yml    # Service orchestration

Next Steps

  1. Replace ML stubs with real models:

    • Implement actual OCR model architecture in backend/src/ml/ocr/model.py
    • Implement classifier in backend/src/ml/classifier/model.py
    • Update inference engines with real preprocessing and postprocessing

  2. Implement C library:

    • Add actual postprocessing logic in c_library/src/postprocess.c
    • Update Python bindings in backend/src/ml/postprocessing/c_bindings.py

  3. Add training datasets:

    • Place training data in data/ directory
    • Implement dataset loaders in training scripts

  4. Enhance frontend:

    • Add more visualizations
    • Implement image cropping/editing
    • Add user authentication

  5. Production hardening:

    • Add proper logging and monitoring
    • Implement rate limiting
    • Add database for persistent storage
    • Set up CI/CD pipeline
    • Add security headers and HTTPS