What's New in v1.3.0

Runtime Backend API Configuration

The SPA now resolves the backend API URL at runtime via the BACKEND_API_URL environment variable — no rebuild needed. This works in Docker, Coolify, and local development.

• Docker: Set BACKEND_API_URL in your compose environment
• Dev: spa-dev.py sets it automatically
• Coolify: Configure via the service environment variables UI

Highlights

• AppInitializer component shows a spinner while loading config, with error/retry on failure
• /api/config server-side endpoint returns the backend URL to the SPA client
• /health route on SPA redirects to the Django backend health endpoint
• Removed NEXT_PUBLIC_API_BASE_URL build-time dependency from Dockerfile

Migration from v1.2.x

• Docker: Set BACKEND_API_URL environment variable on the SPA service (e.g., http://lpr-app:8000)
• spa-dev.py: Automatically uses the new variable — no action needed
• Backward compat: NEXT_PUBLIC_API_BASE_URL still works as a fallback

Full Changelog: v1.2.3...v1.3.0

Changed

• Add path filters to Django backend CI workflow to reduce CI noise on docs-only changes

Full Changelog: v1.2.1...v1.2.2

Fixed

• Grant contents:write permission to Docker publish workflows for SBOM release attachment

Removed

• Deleted .roo/ directory (Roo Code IDE config artifacts)
• Deleted nginx/ directory (unused — Traefik is the active reverse proxy)

Full Changelog: v1.2.0...v1.2.1

What's New in v1.2.0

Breaking Changes

• Django backend is now API-only — all server-rendered templates, forms, and web views have been removed. The frontend is served entirely by the Next.js SPA.

Highlights

• Django 5.2 LTS — upgraded from 4.2 (supported through April 2028), Python 3.10+ required
• Next.js 16 SPA — modern React 19 frontend with Tailwind CSS 4, replacing the Bootstrap/Django template UI
• Storybook 10 — component development environment with stories for all UI components
• Dark Mode — full light/dark theme support with system preference detection
• New API Endpoints — /api/v1/images/, /api/v1/images/<id>/, /api/v1/download/<id>/<type>/, /api/v1/config/
• CORS Support — django-cors-headers for SPA cross-origin requests
• Configurable OCR Crop Padding — fixed-pixel padding for OCR crop regions

Cleanup

• Removed all Django HTML templates, forms, template tags, and web views
• Removed nginx/ directory (Traefik is the active reverse proxy)
• Removed legacy monolithic views.py and views_refactored.py

Full Changelog: v1.1.0...v1.2.0

Open LPR v1.1.0 Release Notes

We're excited to announce Open LPR v1.1.0! This is a significant feature release that brings monitoring infrastructure, improved Docker deployment, UI enhancements, and numerous bug fixes.

🆕 Major Features

Two-Phase LPR Pipeline with Dynamic Detection Scaling

The license plate recognition pipeline now uses a two-phase approach:

• Phase 1: Detects license plate bounding boxes in the full image
• Phase 2: Runs OCR on cropped plate regions for higher accuracy
• Dynamic scaling adjusts detection parameters based on image characteristics

Comprehensive Monitoring Stack

Full observability stack with custom Docker images:

• Prometheus with LPR app metrics dashboard
• Grafana with pre-built dashboards for both the LPR app and canary service
• Blackbox Exporter for HTTP endpoint probing
• Canary Service for automated health checks and endpoint verification
• Custom monitoring images with embedded configurations, published to GHCR

Profile-Based Docker Compose

Complete Docker Compose refactor using the merge design pattern with profiles:

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

Individual compose files (docker-compose-llamacpp-cpu.yml, docker-compose-llamacpp-amd-vulcan.yml) are now deprecated.

NVIDIA CUDA GPU Support

Local LlamaCpp inference now supports NVIDIA GPUs with CUDA, in addition to the existing AMD Vulkan and CPU options.

Dark Mode

Comprehensive dark mode support with:

• Automatic system theme detection
• Smooth light/dark mode switching
• Proper styling for all UI components including OCR results and data tables

✨ New Features

• Dynamic font scaling for OCR text visualization on bounding boxes
• Favicon for the LPR application
• Star History chart added to README
• Coolify deployment support with custom Docker images
• Configurable Traefik router rules via environment variables
• Configurable service ports to avoid deployment conflicts
• CSRF trusted origins configuration for cross-origin requests
• Simplified mobile pagination for better mobile experience
• Liability disclaimer in application header
• Live demo link in README pointing to https://rest-openlpr.computedsynergy.com/

🔧 Changed

• Code architecture: Split monolithic views.py into modular view components (views/ subpackage with web_views.py, api_views.py, file_views.py)
• Homepage: Now shows 9 processed images with annotations
• Image list page: Shows annotated images with OCR text and plate count instead of just filenames
• UI layout: Condensed vertical space for better screen utilization
• Upload size: Maximum reduced from 10MB to 250KB for optimized processing
• README: Reorganized with collapsible sections and compact navigation
• License: Changed from MIT to Apache 2.0

🐛 Bug Fixes

Infrastructure Fixes

• Fixed django.logstatic typo in docker-entrypoint.sh causing chown error on startup
• Fixed metrics directory permissions by adding /app/metrics to Dockerfile
• Fixed metrics state file (metrics_state.json) creation and permissions in entrypoint
• Fixed database file ownership to prevent readonly database errors in containers
• Fixed multi-platform Docker build issue
• Fixed Traefik Docker API compatibility issue

Monitoring Fixes

• Fixed canary service HTTP 502 error and connectivity issues
• Fixed canary image cleanup functionality
• Fixed canary dashboard configuration and connectivity
• Fixed Prometheus and Blackbox Exporter duplicate binary names in CMD
• Fixed Grafana provisioning duplicate UID warnings
• Fixed metrics endpoint errors

Application Fixes

• Fixed hardcoded API response data in LPR processing
• Fixed KeyError in get_first_ocr_text() method for mixed OCR data formats
• Fixed OCR results display in dark mode
• Fixed pagination URL encoding and error handling
• Fixed reverse pagination on image list page
• Fixed duplicate timestamps (removed redundant ones)
• Fixed display of correct max file size on upload page
• Eliminated duplicate Traefik configuration
• Fixed navigation links in README.md

📦 Dependency Updates

🐳 Docker Images

The v1.1.0 release includes updated Docker images:

• ghcr.io/faisalthaheem/open-lpr:latest — Latest stable version (now v1.1.0)
• ghcr.io/faisalthaheem/open-lpr:v1.1.0 — Version 1.1.0
• ghcr.io/faisalthaheem/open-lpr:v1.1 — Version 1.1.x series
• ghcr.io/faisalthaheem/open-lpr:v1 — Version 1.x series (latest minor)

Images are available for both linux/amd64 and linux/arm64 architectures.

⚠️ Deprecated

• Individual Docker Compose files (docker-compose-llamacpp-cpu.yml, docker-compose-llamacpp-amd-vulcan.yml)
• Migrate to profile-based approach: docker compose --profile core --profile <inference-profile> up -d

📋 API Changes

No breaking changes to the API in this release. All existing endpoints remain compatible with v1.0.0.

🔄 Upgrade Instructions

Docker Deployment (Profile-Based — Recommended)

# Pull the latest images
docker compose pull

# Restart with your preferred profile
docker compose --profile core --profile <cpu|nvidia-cuda|amd-vulkan> up -d

From Deprecated Individual Compose Files

# Old (deprecated)
docker compose -f docker-compose-llamacpp-cpu.yml pull
docker compose -f docker-compose-llamacpp-cpu.yml up -d

# New (recommended)
docker compose --profile core --profile cpu pull
docker compose --profile core --profile cpu up -d

Source Installation

git fetch origin
git checkout v1.1.0
pip install -r requirements.txt
python manage.py migrate
# Restart your application server

🛠️ Migration Notes

• No database migrations required for this release
• All configuration files remain compatible
• No breaking changes to existing functionality
• If using deprecated individual compose files, migrate to profile-based approach

🐛 Known Issues

• Large images (>250KB) are rejected at upload to ensure optimal performance
• Some very old OCR data formats may require manual migration

🔒 Security

• Django security patches included through version 4.2.30
• Pillow security patches included through version 12.2.0
• Non-root Docker user maintained
• Input validation and sanitization maintained
• CSRF protection with trusted origins support

🙏 Acknowledgments

Thank you to all users who reported issues, provided feedback, and contributed to this release! Special thanks to Dependabot for keeping dependencies up to date.

📄 License

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

Thank you for using Open LPR! 🎉

If you encounter any issues or have questions, please file an issue on GitHub.

Open LPR v1.0.1 Release Notes

We're pleased to announce the release of Open LPR v1.0.1! This is a maintenance release that focuses on bug fixes, UI improvements, and enhanced user experience based on feedback from the initial release.

🐛 Bug Fixes

Critical Fixes

• Fix KeyError in get_first_ocr_text() method: Handle both new and old OCR data formats to prevent crashes when displaying OCR text on the /images/ page
• Fix OCR results display in dark mode: Remove debug styling and ensure proper dark mode compatibility for OCR text and tables
• Fix pagination URL encoding and error handling: Resolve issues with pagination functionality on image list pages
• Fix reverse pagination on image list page: Correct pagination direction for better user experience
• Fix hardcoded API response data in LPR processing: Ensure dynamic and accurate processing results

UI/UX Fixes

• Fix display of correct max file size on upload page: Show accurate file size limits to users
• Fix duplicate timestamps: Remove redundant timestamp displays, keeping only processing time
• Ensure database file ownership: Prevent readonly database errors in containerized deployments

✨ New Features

User Interface Enhancements

• Add comprehensive dark mode support: Implement system theme detection with automatic dark/light mode switching
• Add favicon for LPR application: Improve brand recognition with a custom favicon
• Display annotated images in image list page: Show processed images with bounding boxes directly in the list view
• Update index page to show 9 processed images: Enhance homepage with visual examples of processed images
• Update UI to show OCR text instead of filename: Display more meaningful information in image listings
• Add plate count display: Show the number of license plates detected in each image

Layout Improvements

• Condense vertical space on index page: Optimize layout for better screen utilization
• Further condense vertical space and improve layout: Refine overall UI density and visual hierarchy

🔧 Technical Improvements

Dependencies

• Update Django from 4.2.7 to 4.2.27: Include latest security patches and bug fixes
• Update Pillow from 10.1.0 to 10.3.0: Incorporate latest image processing improvements and security updates

Configuration

• Add CSRF trusted origins configuration: Enable cross-origin requests for enhanced integration capabilities
• Add environment file template: Improve setup experience with configuration examples

Documentation

• Improve README organization: Add collapsible sections and compact navigation for better readability
• Add comprehensive liability disclaimer to header: Ensure proper legal coverage
• Update license to Apache 2.0: Switch to more permissive open-source license
• Add live demo section: Showcase working application for potential users

🔄 Changes Since v1.0.0

File Upload Changes

• Reduce maximum image upload size from 10MB to 250KB: Optimize for faster processing and reduced resource usage

Homepage Updates

• Updated homepage from generic GitHub to project page: Provide dedicated project landing page
• Enhanced visual presentation: Better showcase of application capabilities

📋 API Changes

No breaking changes to the API in this release. All existing endpoints remain compatible with v1.0.0.

🐳 Docker Images

The v1.0.1 release includes updated Docker images with the latest fixes and improvements:

• ghcr.io/faisalthaheem/open-lpr:latest - Latest stable version (now v1.0.1)
• ghcr.io/faisalthaheem/open-lpr:v1.0.1 - Version 1.0.1
• ghcr.io/faisalthaheem/open-lpr:v1.0 - Version 1.0.x series (latest patch)
• ghcr.io/faisalthaheem/open-lpr:v1 - Version 1.x series (latest minor)

Images are available for both linux/amd64 and linux/arm64 architectures.

🔄 Upgrade Instructions

From v1.0.0 to v1.0.1

Docker Deployment

# Pull the latest image
docker-compose pull

# Restart the services
docker-compose up -d

LlamaCpp Deployment

# Pull the latest image
docker-compose -f docker-compose-llamacpp-cpu.yml pull

# Restart the services
docker-compose -f docker-compose-llamacpp-cpu.yml up -d

Source Installation

# Pull the latest changes
git fetch origin
git checkout v1.0.1

# Update dependencies
pip install -r requirements.txt

# Restart your application server

🛠️ Migration Notes

• No database migrations required for this release
• All configuration files remain compatible
• No breaking changes to existing functionality

🐛 Known Issues

• Large images (>250KB) are now rejected at upload to ensure optimal performance
• Some very old OCR data formats may require manual migration (contact support if needed)

🙏 Acknowledgments

Thank you to all users who reported issues and provided feedback for this release! Your contributions help make Open LPR more reliable and user-friendly.

📄 License

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

Thank you for using Open LPR! 🎉

If you encounter any issues or have questions, please file an issue on GitHub.

For more information about Open LPR, visit our main repository.

🎉 Open LPR v1.0.0 - First Major Release!

We're excited to announce the first major release of Open LPR - a powerful, open-source License Plate Recognition system powered by AI!

✨ Key Features

• 🤖 AI-Powered Detection: Uses qwen3-vl-4b-instruct vision-language model for accurate license plate recognition
• 🔍 Advanced OCR Integration: Extracts text from detected license plates with confidence scores
• 🎯 Bounding Box Visualization: Draws colored boxes around detected plates and OCR text
• 📤 Drag & Drop Upload: Modern, user-friendly file upload interface
• 💾 Permanent Storage: All uploaded and processed images are saved permanently
• 🔄 Side-by-Side Comparison: View original and processed images together
• 🔎 Search & Filter: Browse and search through processing history
• 📱 Responsive Design: Works on desktop, tablet, and mobile devices
• 🐳 Docker Support: Easy deployment with Docker and Docker Compose
• 🔌 REST API: Full API for programmatic access

🚀 Deployment Options

1. Standard Docker Deployment: Traditional deployment with cloud-based AI services
2. LlamaCpp CPU Deployment: Local inference using CPU resources
3. LlamaCpp GPU Deployment: Local inference with AMD GPU acceleration using Vulkan

📦 What's New in v1.0.0

Core Application

• Complete Django web application with license plate recognition capabilities
• RESTful API with comprehensive endpoints for image processing
• User-friendly web interface with drag-and-drop upload functionality
• Image processing pipeline with bounding box visualization
• Search and filter functionality for processed images
• Responsive design that works across all devices

Docker Deployment

• Multi-stage optimized Dockerfile for production use
• Automated CI/CD pipeline with GitHub Actions
• Multi-architecture support (linux/amd64, linux/arm64)
• Automatic publishing to GitHub Container Registry
• Software Bill of Materials (SBOM) generation for security scanning

LlamaCpp Integration

• Local inference support with LlamaCpp server
• CPU and GPU deployment options
• Comprehensive documentation for local deployment
• Environment configuration templates
• Model download automation

🐳 Docker Images

The v1.0.0 release includes Docker images published to GitHub Container Registry:

• ghcr.io/faisalthaheem/open-lpr:latest - Latest stable version
• ghcr.io/faisalthaheem/open-lpr:v1.0.0 - Version 1.0.0
• ghcr.io/faisalthaheem/open-lpr:v1.0 - Version 1.0.x series
• ghcr.io/faisalthaheem/open-lpr:v1 - Version 1.x series

Images are available for both linux/amd64 and linux/arm64 architectures.

📥 Quick Start

Standard Docker Deployment

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

# Copy environment file
cp .env.example .env

# Edit the environment file with your configuration
nano .env

# Run with Docker Compose
docker-compose up -d

LlamaCpp CPU Deployment

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

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

# Edit the environment file with your HuggingFace token
nano .env.llamacpp

# Run with Docker Compose
docker-compose -f docker-compose-llamacpp-cpu.yml up -d

📚 Documentation

• Main README - Project overview and quick start guide
• Docker Deployment Guide - Comprehensive Docker deployment instructions
• LlamaCpp Deployment Guide - Local inference with LlamaCpp server
• API Documentation - Complete REST API reference
• LlamaCpp Resources - Important URLs and documentation links

🐛 Known Issues

• Large images (>10MB) may require increased memory allocation
• GPU acceleration is currently limited to AMD GPUs with Vulkan support
• Concurrent processing is limited by Django's development server (use Gunicorn in production)

🛣️ Roadmap

Future releases will include:

• Support for additional GPU types (NVIDIA CUDA)
• Batch processing capabilities
• Real-time video stream processing
• Additional language support for license plates
• Performance optimizations
• Mobile application

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

📄 License

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

🙏 Acknowledgments

• Qwen3-VL for the powerful vision-language model
• Django for the robust web framework
• Bootstrap for the responsive UI components
• LlamaCpp for local inference capabilities
• All contributors who help improve this project

Thank you for using Open LPR! 🎉

If you encounter any issues or have questions, please file an issue on GitHub.