# 🚀 Hugging Face Spaces Deployment Guide

## Overview

This guide provides step-by-step instructions for deploying the Legal Dashboard OCR system to Hugging Face Spaces using the Docker SDK.

## 📋 Prerequisites

- Hugging Face account
- Git repository with the project
- Docker installed locally (for testing)

## 🏗️ Project Structure

```
legal_dashboard_ocr/
├── Dockerfile              # Docker container definition
├── .dockerignore          # Files to exclude from Docker build
├── docker-compose.yml     # Local testing configuration
├── requirements.txt       # Python dependencies
├── README.md             # HF Spaces metadata + documentation
├── app/                  # FastAPI application
│   ├── main.py          # Main application entry point
│   ├── api/             # API route handlers
│   ├── services/        # Business logic services
│   └── models/          # Data models
├── frontend/            # Web interface files
├── data/               # Sample documents
└── tests/              # Test suite
```

## 🔧 Local Testing

### 1. Build Docker Image

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

### 2. Test Locally

```bash
# Using docker run
docker run -p 7860:7860 legal-dashboard-ocr

# Or using docker-compose
docker-compose up
```

### 3. Verify Deployment

- **Dashboard**: http://localhost:7860
- **API Docs**: http://localhost:7860/docs
- **Health Check**: http://localhost:7860/health

## 🚀 Hugging Face Spaces Deployment

### Step 1: Create New Space

1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Choose settings:
   - **Owner**: Your username
   - **Space name**: `legal-dashboard-ocr`
   - **SDK**: `Docker`
   - **License**: Choose appropriate license

### Step 2: Upload Code

```bash
# Clone your repository (if not already done)
git clone <your-repo-url>
cd legal_dashboard_ocr

# Push to Hugging Face Space
git remote add space https://huggingface.co/spaces/<username>/legal-dashboard-ocr
git push space main
```

### Step 3: Monitor Deployment

1. Go to your Space page
2. Check the "Build logs" tab
3. Wait for build completion (usually 5-10 minutes)
4. Verify the Space is running on port 7860

## 🔍 Verification Checklist

### ✅ Docker Build
- [ ] Dockerfile exists and is valid
- [ ] .dockerignore excludes unnecessary files
- [ ] Requirements.txt has all dependencies
- [ ] Port 7860 is exposed

### ✅ Application Configuration
- [ ] Main.py runs on port 7860
- [ ] Health endpoint responds correctly
- [ ] CORS is configured for HF Spaces
- [ ] Static files are served correctly

### ✅ HF Spaces Metadata
- [ ] README.md has correct YAML header
- [ ] SDK is set to "docker"
- [ ] Title and emoji are set
- [ ] Colors are configured

### ✅ API Endpoints
- [ ] `/` - Dashboard interface
- [ ] `/health` - Health check
- [ ] `/docs` - API documentation
- [ ] `/api/ocr/process` - OCR processing
- [ ] `/api/dashboard/summary` - Dashboard data

## 🐛 Troubleshooting

### Common Issues

1. **Build Fails**
   - Check Dockerfile syntax
   - Verify all dependencies in requirements.txt
   - Check .dockerignore excludes too many files

2. **Container Won't Start**
   - Verify port 7860 is exposed
   - Check CMD instruction in Dockerfile
   - Review application logs

3. **API Endpoints Not Working**
   - Verify CORS configuration
   - Check route definitions
   - Test locally first

4. **Static Files Not Loading**
   - Check file paths in main.py
   - Verify files are copied to container
   - Test static file serving

### Debug Commands

```bash
# Check container logs
docker logs <container-id>

# Enter container for debugging
docker exec -it <container-id> /bin/bash

# Test health endpoint
curl http://localhost:7860/health

# Check container status
docker ps
```

## 📊 Performance Optimization

### Docker Optimizations
- Multi-stage builds for smaller images
- Layer caching for faster builds
- Alpine Linux base for minimal size

### Application Optimizations
- Async/await for I/O operations
- Connection pooling for database
- Caching for OCR models
- Compression for static files

## 🔒 Security Considerations

### Container Security
- Non-root user in container
- Minimal base image
- Regular security updates
- No sensitive data in image

### Application Security
- Input validation on all endpoints
- Rate limiting for API calls
- Secure file upload handling
- CORS configuration

## 📈 Monitoring

### Health Checks
- Application health endpoint
- Database connectivity
- OCR service availability
- Memory and CPU usage

### Logging
- Structured logging with timestamps
- Error tracking and alerting
- Performance metrics
- User activity monitoring

## 🎯 Success Criteria

✅ **Deployment Successful**
- Space builds without errors
- Application starts on port 7860
- Health endpoint returns 200 OK

✅ **Functionality Verified**
- Dashboard loads correctly
- OCR processing works
- API endpoints respond
- File uploads function

✅ **Performance Acceptable**
- Page load times < 3 seconds
- OCR processing < 30 seconds
- API response times < 1 second

## 🚀 Next Steps

1. **Monitor Performance**: Track usage and performance metrics
2. **Add Features**: Implement additional OCR capabilities
3. **Scale**: Optimize for higher traffic
4. **Security**: Implement additional security measures
5. **Documentation**: Update user documentation

---

**🎉 Congratulations!** Your Legal Dashboard OCR system is now deployed on Hugging Face Spaces with Docker SDK.