DEPLOYMENT_GUIDE.md

Legal Dashboard OCR - Deployment Guide

Quick Start

Using Docker Compose (Recommended)

1. Build and run the application:

   cd legal_dashboard_ocr
   docker-compose up --build
   

2. Access the application:

   • Open your browser and go to: http://localhost:7860
   • The application will be available on port 7860

Using Docker directly

1. Build the Docker image:

   cd legal_dashboard_ocr
   docker build -t legal-dashboard-ocr .
   

2. Run the container:

   docker run -p 7860:7860 -v $(pwd)/data:/app/data -v $(pwd)/cache:/app/cache legal-dashboard-ocr
   

Troubleshooting

Database Connection Issues

If you encounter database connection errors:

1. Check if the data directory exists:

   docker exec -it <container_name> ls -la /app/data
   

2. Create the data directory manually:

   docker exec -it <container_name> mkdir -p /app/data
   docker exec -it <container_name> chmod 777 /app/data
   

3. Test database connection:

   docker exec -it <container_name> python debug_container.py
   

OCR Model Issues

If OCR models fail to load:

1. Check available models: The application will automatically try these models in order:

   • microsoft/trocr-base-stage1
   • microsoft/trocr-base-handwritten
   • microsoft/trocr-small-stage1
   • microsoft/trocr-small-handwritten

2. Set Hugging Face token (optional):

   export HF_TOKEN=your_huggingface_token
   docker run -e HF_TOKEN=$HF_TOKEN -p 7860:7860 legal-dashboard-ocr
   

Container Logs

To view container logs:

docker-compose logs -f

Or for direct Docker:

docker logs <container_name> -f

Environment Variables

Variable	Default	Description
DATABASE_PATH	/app/data/legal_dashboard.db	SQLite database path
TRANSFORMERS_CACHE	/app/cache	Hugging Face cache directory
HF_HOME	/app/cache	Hugging Face home directory
HF_TOKEN	(not set)	Hugging Face authentication token

Volume Mounts

The application uses these volume mounts for persistent data:

• ./data:/app/data - Database and uploaded files
• ./cache:/app/cache - Hugging Face model cache

Health Check

The application includes a health check endpoint:

• URL: http://localhost:7860/health
• Returns status of OCR, database, and AI services

Common Issues and Solutions

Issue: "unable to open database file"

Solution:

1. Ensure the data directory exists and has proper permissions
2. Check if the volume mount is working correctly
3. Run the debug script: docker exec -it <container> python debug_container.py

Issue: OCR models fail to load

Solution:

1. The application will automatically fall back to basic text extraction
2. Check internet connectivity for model downloads
3. Set HF_TOKEN if you have Hugging Face access

Issue: Container fails to start

Solution:

1. Check Docker logs: docker logs <container_name>
2. Ensure port 7860 is not already in use
3. Verify Docker has enough resources (memory/disk)

Development

Local Development

1. Install dependencies:

   pip install -r requirements.txt
   

2. Run locally:

   python -m uvicorn app.main:app --host 0.0.0.0 --port 7860
   

Testing

1. Test database connection:

   python test_db_connection.py
   

2. Test container environment:

   docker run --rm legal-dashboard-ocr python debug_container.py
   

Performance Optimization

1. Model caching: The application caches Hugging Face models in /app/cache
2. Database optimization: SQLite database is optimized for concurrent access
3. Memory usage: Consider increasing Docker memory limits for large models

Security Considerations

1. Database security: SQLite database is stored in a volume mount
2. API security: Consider adding authentication for production use
3. File uploads: Implement file size limits and type validation

Monitoring

The application provides:

• Health check endpoint: /health
• Real-time logs via Docker
• System metrics in the database

Support

For issues not covered in this guide:

1. Check the application logs
2. Run the debug script
3. Verify Docker and system resources