The quickest way to get started is with Docker using the new profile-based compose file, which includes everything needed for local inference without requiring any external API endpoints.

🚨 Stability Notice: For production environments, we strongly recommend using tagged releases instead of the mainline branch. See the Production Deployment section for stable version instructions.

🚨 Important Notice: Individual compose files (docker-compose-llamacpp-*.yml) are now deprecated. Please use the new profile-based approach with the main docker-compose.yml file.

For users with AMD GPUs that support Vulkan:

# Clone the repository
git clone https://github.com/faisalthaheem/open-lpr.git
cd open-lpr

# Create environment file from template
cp .env.llamacpp.example .env.llamacpp

# Edit the environment file with your settings
nano .env.llamacpp

# Create necessary directories
mkdir -p model_files model_files_cache container-data container-media staticfiles

# Start the application with AMD Vulkan GPU support
docker compose --profile core --profile amd-vulkan up -d

# Check the logs to ensure everything is running correctly
docker compose logs -f

For users without compatible GPUs or for testing purposes:

# Clone the repository
git clone https://github.com/faisalthaheem/open-lpr.git
cd open-lpr

# Create environment file from template
cp .env.llamacpp.example .env.llamacpp

# Edit the environment file with your settings
nano .env.llamacpp

# Create necessary directories
mkdir -p model_files model_files_cache container-data container-media staticfiles

# Start the application with CPU support
docker compose --profile core --profile cpu up -d

# Check the logs to ensure everything is running correctly
docker compose logs -f

For users with NVIDIA GPUs that support CUDA:

# Clone the repository
git clone https://github.com/faisalthaheem/open-lpr.git
cd open-lpr

# Create environment file from template
cp .env.llamacpp.example .env.llamacpp

# Edit the environment file with your settings
nano .env.llamacpp

# Create necessary directories
mkdir -p model_files model_files_cache container-data container-media staticfiles

# Start the application with NVIDIA CUDA GPU support
docker compose --profile core --profile nvidia-cuda up -d

# Check the logs to ensure everything is running correctly
docker compose logs -f

For users who want to use an external OpenAI-compatible API endpoint:

# Clone the repository
git clone https://github.com/faisalthaheem/open-lpr.git
cd open-lpr

# Create environment file from template
cp .env.example .env

# Edit the environment file with your API settings
nano .env

# Create necessary directories
mkdir -p container-data container-media staticfiles

# Start the application (core services only)
docker compose --profile core up -d

# Check the logs to ensure everything is running correctly
docker compose logs -f

🚨 Deprecation Notice: Individual compose files (docker-compose-llamacpp-*.yml) are now deprecated and will be removed in a future release. Please migrate to the new profile-based approach using the main docker-compose.yml file.

The main docker-compose.yml now uses the merge design pattern with profiles for flexible deployment:

Profiles Available:

• core: Core infrastructure (Traefik, OpenLPR, Prometheus, Grafana, Blackbox Exporter, Canary)
• cpu: CPU-based LlamaCpp inference
• amd-vulkan: AMD Vulkan GPU inference
• nvidia-cuda: NVIDIA CUDA GPU inference

Usage Examples:

# Core infrastructure + CPU inference
docker compose --profile core --profile cpu up -d

# Core infrastructure + NVIDIA inference
docker compose --profile core --profile nvidia-cuda up -d

# Core infrastructure + AMD Vulkan inference
docker compose --profile core --profile amd-vulkan up -d

# Core services only (for external API)
docker compose --profile core up -d

# Stop all services
docker compose down

Access Points:

• OpenLPR App: http://lpr.localhost
• Traefik Dashboard: http://traefik.localhost
• Prometheus: http://prometheus.localhost
• Grafana: http://grafana.localhost (admin/admin)
• Blackbox Exporter: http://blackbox.localhost
• Canary Service: http://canary.localhost

For detailed profile documentation, see README-DOCKER-PROFILES.md.

⚠️ Deprecated: The following compose files are deprecated and will be removed in a future release. Please migrate to the profile-based approach above.

1. docker-compose-llamacpp-amd-vulcan.yml (Deprecated)

   • Replaced by: docker compose --profile core --profile amd-vulkan up -d
   • Was: Full local deployment with AMD GPU acceleration using Vulkan

2. docker-compose-llamacpp-cpu.yml (Deprecated)

   • Replaced by: docker compose --profile core --profile cpu up -d
   • Was: Full local deployment using CPU for inference

3. docker-compose.yml (Legacy external API mode)

   • Replaced by: docker compose --profile core up -d
   • Was: OpenLPR deployment with external API endpoint

For development or custom deployments:

1. Prerequisites

   • Python 3.10+
   • pip package manager
   • Qwen3-VL API access

2. Clone the repository

   For production/stable deployments, use a tagged release:

   # List available releases
   git ls-remote --tags https://github.com/faisalthaheem/open-lpr.git
   
   # Clone a specific stable version (recommended for production)
   git clone --branch v1.0.0 https://github.com/faisalthaheem/open-lpr.git
   cd open-lpr
   
   # Or clone the latest stable release
   git clone --branch $(git ls-remote --tags https://github.com/faisalthaheem/open-lpr.git | grep -v 'rc\|beta\|alpha' | tail -n1 | sed 's/.*\///') https://github.com/faisalthaheem/open-lpr.git
   cd open-lpr

   For development/testing (may be unstable):

   git clone https://github.com/faisalthaheem/open-lpr.git
   cd open-lpr

3. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

4. Install dependencies

   pip install -r requirements.txt

5. Configure environment variables

   cp .env.example .env
   # Edit .env with your settings

6. Set up database

   python manage.py makemigrations
   python manage.py migrate

7. Create superuser (optional)

   python manage.py createsuperuser

8. Run development server

   python manage.py runserver

9. Access the application Open http://127.0.0.1:8000 in your browser

For local development (running Django directly):

Create a .env file based on .env.example:

# Django Settings
SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Qwen3-VL API Configuration
QWEN_API_KEY=your-qwen-api-key
QWEN_BASE_URL=https://your-open-api-compatible-endpoint.com/v1
QWEN_MODEL=qwen3-vl-4b-instruct

# File Upload Settings
UPLOAD_FILE_MAX_SIZE=10485760  # 10MB
MAX_BATCH_SIZE=10

For local LlamaCpp inference deployment:

Create a .env.llamacpp file based on .env.llamacpp.example:

# HuggingFace Token
HF_TOKEN=hf_your_huggingface_token_here

# Model Configuration
MODEL_REPO=unsloth/Qwen3-VL-4B-Instruct-GGUF
MODEL_FILE=Qwen3-VL-4B-Instruct-Q5_K_M.gguf
MMPROJ_URL=https://huggingface.co/unsloth/Qwen3-VL-4B-Instruct-GGUF/resolve/main/mmproj-BF16.gguf

# Django Settings
SECRET_KEY=your-secret-key-here
DEBUG=False
ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0

# File Upload Settings
UPLOAD_FILE_MAX_SIZE=10485760  # 10MB
MAX_BATCH_SIZE=10

# Database Configuration
DATABASE_PATH=/app/data/db.sqlite3

# Optional: Superuser creation
DJANGO_SUPERUSER_USERNAME=admin
DJANGO_SUPERUSER_EMAIL=admin@example.com
DJANGO_SUPERUSER_PASSWORD=your-secure-password

# Qwen3-VL API Configuration
QWEN_API_KEY=sk-llamacpp-local
#when using a remote Open API compatible endpoint
# QWEN_BASE_URL=https://your-api-endpoint.io/v1
#When running bundled llamacpp using CPU (default)
QWEN_BASE_URL=http://llamacpp-cpu:8000/v1
#When running bundled llamacpp using AMD GPUs
# QWEN_BASE_URL=http://llamacpp-amd-vulkan:8000/v1
#When running bundled llamacpp using Nvidia GPUs
# QWEN_BASE_URL=http://llamacpp-nvidia-cuda:8000/v1
QWEN_MODEL=Qwen3-VL-4B-Instruct

For detailed LlamaCpp deployment instructions, see README-llamacpp.md.

1. Drag & Drop: Simply drag an image file onto the upload area
2. Click to Browse: Click the upload area to select a file
3. File Validation:
   • Supported formats: JPEG, PNG, WEBP
   • Maximum size: configurable (default 1MB dev / 10MB Docker)
4. Processing: Click "Analyze License Plates" to start detection

After processing, you'll see:

• Detection Summary: Number of plates and OCR texts found
• Image Comparison: Side-by-side view of original and processed images
• Detection Details:
  • License plate coordinates and confidence
  • OCR text results with confidence scores
  • Bounding box coordinates for all detections
• Download Options: Download both original and processed images

Access the "History" page to:

• Search: Filter by filename
• Date Range: Filter by upload date
• Status Filter: View by processing status
• Pagination: Navigate through large numbers of uploads

• POST /api/v1/ocr/ - Upload an image and receive OCR results synchronously
• GET /api/v1/images/ - List images with pagination and filtering
• GET /api/v1/images/<int:image_id>/ - Get detailed information about a specific image
• GET /api/v1/download/<int:image_id>/<str:image_type>/ - Download original or processed images
• GET /api/v1/config/ - Get application configuration (max upload size, timeout)
• GET /metrics/ - Prometheus metrics endpoint

The LPR REST API returns JSON in this format:

{
    "success": true,
    "image_id": 123,
    "filename": "example.jpg",
    "processing_time_ms": 2450,
    "results": {
        "detections": [
            {
                "plate_id": "plate1",
                "plate": {
                    "confidence": 0.85,
                    "coordinates": {
                        "x1": 100,
                        "y1": 200,
                        "x2": 250,
                        "y2": 250
                    }
                },
                "ocr": [
                    {
                        "text": "ABC123",
                        "confidence": 0.92,
                        "coordinates": {
                            "x1": 105,
                            "y1": 210,
                            "x2": 245,
                            "y2": 240
                        }
                    }
                ]
            }
        ]
    },
    "summary": {
        "total_plates": 1,
        "total_ocr_texts": 1
    },
    "processing_timestamp": "2023-12-07T15:30:45.123456"
}

{
    "success": false,
    "error": "No image file provided",
    "error_code": "MISSING_IMAGE"
}

import requests

# API endpoint
url = "http://localhost:8000/api/v1/ocr/"

# Image file to upload
image_path = "license_plate.jpg"

# Read and upload the image
with open(image_path, 'rb') as f:
    files = {'image': f}
    response = requests.post(url, files=files)

# Check response
if response.status_code == 200:
    result = response.json()
    if result['success']:
        print(f"Found {result['summary']['total_plates']} license plates")
        for detection in result['results']['detections']:
            for ocr in detection['ocr']:
                print(f"License plate text: {ocr['text']} (confidence: {ocr['confidence']:.2f})")
    else:
        print(f"Processing failed: {result['error']}")
else:
    print(f"HTTP Error: {response.status_code}")
    print(response.text)

# Upload image and get OCR results
curl -X POST \
  -F "image=@license_plate.jpg" \
  http://localhost:8000/api/v1/ocr/

The project includes automated Docker image building and publishing to GitHub Container Registry (ghcr.io).

The Docker image is automatically built and published to GitHub Container Registry when code is pushed to the main branch or when tags are created.

🚨 Production Recommendation: For production deployments, always use versioned tags instead of latest. The latest tag may contain unstable features from the mainline branch.

# Pull a specific stable version (recommended for production)
docker pull ghcr.io/faisalthaheem/open-lpr:v1.0.0

# List available versions
curl -s "https://api.github.com/repos/faisalthaheem/open-lpr/releases" | grep -o '"tag_name": "v[^"]*"' | head -10

# Pull the latest stable release (excluding pre-releases)
LATEST_STABLE=$(curl -s "https://api.github.com/repos/faisalthaheem/open-lpr/releases" | grep -o '"tag_name": "v[^"]*"' | grep -v 'rc\|beta\|alpha' | head -1 | sed 's/"tag_name": "\(.*\)"/\1/')
docker pull ghcr.io/faisalthaheem/open-lpr:$LATEST_STABLE

# Pull the latest image (mainline, may be unstable)
docker pull ghcr.io/faisalthaheem/open-lpr:latest

# Pull a specific pre-release version
docker pull ghcr.io/faisalthaheem/open-lpr:v1.1.0-beta.1

🚨 Important: Individual compose files are now deprecated. Please use the new profile-based approach with the main docker-compose.yml file.

This project provides a unified Docker Compose file with profiles for different deployment scenarios. For detailed deployment instructions, see the Quick Start section and Docker Deployment Guide.

# Core infrastructure + CPU inference
docker compose --profile core --profile cpu up -d

# Core infrastructure + NVIDIA inference
docker compose --profile core --profile nvidia-cuda up -d

# Core infrastructure + AMD Vulkan inference
docker compose --profile core --profile amd-vulkan up -d

# Core services only (for external API)
docker compose --profile core up -d

# Stop all services
docker compose down

For local inference deployments, copy and configure the environment file:

# Copy the example environment file
cp .env.llamacpp.example .env.llamacpp

# Edit with your settings
nano .env.llamacpp

For external API deployments:

# Copy the example environment file
cp .env.example .env

# Edit with your API settings
nano .env

After starting the services:

• OpenLPR Application: http://lpr.localhost
• Traefik Dashboard: http://traefik.localhost
• Prometheus: http://prometheus.localhost
• Grafana: http://grafana.localhost (admin/admin)
• Blackbox Exporter: http://blackbox.localhost
• Canary Service: http://canary.localhost

For comprehensive deployment instructions, including production configurations, see DOCKER_DEPLOYMENT.md and README-DOCKER-PROFILES.md.

The project includes a GitHub Actions workflow (.github/workflows/docker-publish.yml) that:

1. Triggers on:

   • Push to main/master branch
   • Creation of version tags (v*)
   • Pull requests to main/master

2. Builds the Docker image for multiple architectures:

   • linux/amd64
   • linux/arm64

3. Publishes to GitHub Container Registry with tags:

   • Branch name (e.g., main)
   • Semantic version tags (e.g., v1.0.0, v1.0, v1)
   • latest tag for the main branch

4. Generates SBOM (Software Bill of Materials) for security scanning

Use the provided test script to verify API functionality:

# Test with default image locations
python test_api.py

# Test with specific image
python test_api.py /path/to/your/image.jpg

🚨 Critical Production Requirement: Always use tagged releases for production deployments. The mainline branch may contain experimental features and be unstable. Never use latest tags or main branch in production environments.

# Find the latest stable release
curl -s "https://api.github.com/repos/faisalthaheem/open-lpr/releases" | grep -o '"tag_name": "v[^"]*"' | grep -v 'rc\|beta\|alpha' | head -1

# Clone a specific stable version
git clone --branch v1.0.0 https://github.com/faisalthaheem/open-lpr.git
cd open-lpr

# Or checkout an existing repository to a stable version
git fetch --tags
git checkout v1.0.0

# Automatically get the latest stable release (excluding pre-releases)
LATEST_STABLE=$(curl -s "https://api.github.com/repos/faisalthaheem/open-lpr/releases" | grep -o '"tag_name": "v[^"]*"' | grep -v 'rc\|beta\|alpha' | head -1 | sed 's/"tag_name": "\(.*\)"/\1/')
git clone --branch $LATEST_STABLE https://github.com/faisalthaheem/open-lpr.git
cd open-lpr

# Use a specific versioned Docker image (recommended)
VERSION=v1.0.0
docker pull ghcr.io/faisalthaheem/open-lpr:$VERSION

# Update your docker-compose.yml to use the versioned image
sed -i "s|ghcr.io/faisalthaheem/open-lpr:latest|ghcr.io/faisalthaheem/open-lpr:$VERSION|g" docker-compose.yml

# Or automatically use the latest stable release
LATEST_STABLE=$(curl -s "https://api.github.com/repos/faisalthaheem/open-lpr/releases" | grep -o '"tag_name": "v[^"]*"' | grep -v 'rc\|beta\|alpha' | head -1 | sed 's/"tag_name": "\(.*\)"/\1/')
docker pull ghcr.io/faisalthaheem/open-lpr:$LATEST_STABLE

1. Set DEBUG=False in .env
2. Configure ALLOWED_HOSTS with your domain
3. Set up production database (PostgreSQL recommended)
4. Configure static file serving (Traefik/AWS S3)
5. Set up media file serving (Traefik/AWS S3)
6. Use HTTPS with SSL certificate
7. Pin to specific versions (see version selection above)

1. Select a stable version (not latest or main branch)
2. Pin both source code and Docker images to that version
3. Test thoroughly in staging environment
4. Deploy to production with pinned versions
5. Monitor for issues before considering upgrades

For Source Code:

# In your deployment script
VERSION=v1.0.0
git clone --branch $VERSION https://github.com/faisalthaheem/open-lpr.git

For Docker:

# In docker-compose.yml (production)
services:
  openlpr:
    image: ghcr.io/faisalthaheem/open-lpr:v1.0.0  # Pinned version, not latest
    # ... other configuration

• Development: SQLite database, DEBUG=True, mainline branch acceptable
• Staging: PostgreSQL, DEBUG=False, use same version as production
• Production: PostgreSQL, DEBUG=False, HTTPS required, always use tagged releases

1. Check for new stable releases:

   curl -s "https://api.github.com/repos/faisalthaheem/open-lpr/releases" | grep -o '"tag_name": "v[^"]*"' | grep -v 'rc\|beta\|alpha' | head -5

2. Review release notes for breaking changes

3. Test upgrade in staging with the new version

4. Backup production data

5. Deploy with pinned versions following the version selection steps above

6. Monitor and rollback if needed

⚠️Warning: Never upgrade production systems directly from latest tags or mainline branch. Always use specific version tags.

1. API Connection Failed

   • Check QWEN_API_KEY in .env
   • Verify QWEN_BASE_URL is accessible
   • Check network connectivity

2. Image Upload Failed

   • Verify file format (JPEG/PNG/WEBP only)
   • Check file size (within configured limit)
   • Ensure media directory permissions

3. Processing Errors

   • Check Django logs: tail -f django.log
   • Verify API response format
   • Check image processing dependencies

4. Static Files Not Loading

   • Run python manage.py collectstatic
   • Check STATIC_URL in settings
   • Verify web server static file configuration

Application logs are written to:

• Development: Console and django.log
• Production: Configured logging destination

Log levels:

• INFO: General application flow
• ERROR: API failures and processing errors
• DEBUG: Detailed debugging information

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Ensure all tests pass (python manage.py test)
6. Commit your changes (git commit -m 'Add some amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

• Follow PEP 8 for Python code
• Use meaningful variable and function names
• Add docstrings to functions and classes
• Keep commits small and focused

When reporting issues, please include:

• Detailed description of the problem
• Steps to reproduce
• Expected vs. actual behavior
• Environment details (OS, Python version, etc.)
• Relevant logs or error messages

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

For issues and questions:

• Check the troubleshooting section
• Review application logs
• Create an issue with detailed information
• Include error messages and steps to reproduce

• Qwen3-VL for the powerful vision-language model
• Django for the robust web framework
• Next.js for the React-based SPA frontend
• Tailwind CSS for the utility-first CSS framework
• Storybook for component development
• All contributors who help improve this project

For specialized deployment scenarios and additional resources:

• 🆕 Docker Profiles Guide - New profile-based Docker Compose setup (Recommended)
• LlamaCpp and ROCm Resources - Important URLs for local LlamaCpp deployment
• README-llamacpp.md - Local inference with LlamaCpp server
• Docker Deployment Guide - Comprehensive Docker deployment instructions
• API Documentation - Complete REST API reference