DEPLOYMENT_GUIDE.md

# Legal Dashboard OCR - Deployment Guide

## Quick Start

### Using Docker Compose (Recommended)

1. **Build and run the application:**
   ```bash

   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:**
   ```bash

   cd legal_dashboard_ocr

   docker build -t legal-dashboard-ocr .

   ```

2. **Run the container:**
   ```bash

   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:**
   ```bash

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

   ```

2. **Create the data directory manually:**
   ```bash

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

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

   ```

3. **Test database connection:**
   ```bash

   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):**
   ```bash

   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:
```bash

docker-compose logs -f

```

Or for direct Docker:
```bash

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:**

   ```bash

   pip install -r requirements.txt

   ```



2. **Run locally:**

   ```bash

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

   ```



### Testing



1. **Test database connection:**

   ```bash

   python test_db_connection.py

   ```



2. **Test container environment:**

   ```bash

   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