DEPLOYMENT.md

# Deployment Guide for HuggingFace Spaces

## Prerequisites

1. **HuggingFace Account**: Sign up at https://huggingface.co/
2. **Git**: Installed on your local machine
3. **Git LFS**: For large file storage (optional)

## Step-by-Step Deployment

### 1. Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in the details:
   - **Space name**: `pdf-redaction-api` (or your preferred name)
   - **License**: MIT
   - **SDK**: Docker
   - **Hardware**: CPU Basic (free tier) or upgrade if needed
4. Click "Create Space"

### 2. Clone Your Space Repository

```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/pdf-redaction-api
cd pdf-redaction-api
```

### 3. Copy All Files to the Repository

Copy all files from this project to your cloned space:

```bash
# Copy all files
cp -r /path/to/pdf-redaction-api/* .

# Check the files
ls -la
```

You should see:
- `main.py`
- `app/`
- `Dockerfile`
- `requirements.txt`
- `README.md`
- `.gitignore`
- `.dockerignore`
- `uploads/` (with .gitkeep)
- `outputs/` (with .gitkeep)

### 4. Commit and Push

```bash
# Add all files
git add .

# Commit
git commit -m "Initial deployment of PDF Redaction API"

# Push to HuggingFace
git push
```

### 5. Monitor Deployment

1. Go to your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/pdf-redaction-api`
2. You'll see the build logs
3. Wait for the build to complete (usually 5-10 minutes)
4. Once complete, your API will be live!

### 6. Test Your Deployment

```bash
# Check health
curl https://YOUR_USERNAME-pdf-redaction-api.hf.space/health

# Test with a PDF
curl -X POST "https://YOUR_USERNAME-pdf-redaction-api.hf.space/redact" \
  -F "file=@test.pdf" \
  -F "dpi=300"
```

## Configuration Options

### Hardware Upgrades

For better performance, consider upgrading your Space hardware:

1. Go to Space Settings
2. Click on "Hardware"
3. Choose:
   - **CPU Basic** (Free): Good for testing, slower processing
   - **CPU Upgrade** (~$0.50/hour): Faster processing
   - **GPU** (~$0.60-3/hour): Best for large documents

### Environment Variables

Add environment variables in Space Settings if needed:

```bash
HF_HOME=/app/cache
PYTHONUNBUFFERED=1
```

### Persistent Storage

For persistent file storage:

1. Go to Space Settings
2. Enable "Persistent Storage"
3. This keeps uploaded/processed files between restarts

## Custom Domain (Optional)

To use a custom domain:

1. Go to Space Settings
2. Click "Domains"
3. Add your custom domain
4. Follow DNS configuration instructions

## Monitoring and Logs

### View Logs

1. Go to your Space page
2. Click on "Logs" tab
3. Monitor real-time logs

### Check Resource Usage

1. Click on "Insights" tab
2. View CPU/Memory usage
3. Monitor request patterns

## Security Considerations

### For Production Use

1. **Add Authentication**: 
   - Implement API key authentication
   - Use OAuth2 for user management

2. **Rate Limiting**:
   - Add rate limiting to prevent abuse
   - Use slowapi or similar libraries

3. **File Size Limits**:
   - Restrict upload file sizes
   - Implement timeout for long-running requests

4. **HTTPS Only**:
   - HuggingFace Spaces provides HTTPS by default
   - Ensure all requests use HTTPS

Example with API key authentication:

```python
from fastapi import Security, HTTPException, status
from fastapi.security import APIKeyHeader

API_KEY = "your-secret-key"
api_key_header = APIKeyHeader(name="X-API-Key")

def verify_api_key(api_key: str = Security(api_key_header)):
    if api_key != API_KEY:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid API Key"
        )
    return api_key

# Add to endpoints
@app.post("/redact")
async def redact_pdf(
    file: UploadFile = File(...),
    api_key: str = Security(verify_api_key)
):
    # Your code here
```

## Troubleshooting

### Build Fails

**Problem**: Docker build fails

**Solution**:
- Check Dockerfile syntax
- Ensure all dependencies are in requirements.txt
- Review build logs for specific errors

### Out of Memory

**Problem**: API crashes with OOM errors

**Solution**:
- Reduce default DPI to 200
- Upgrade to larger hardware
- Implement request queuing

### Slow Processing

**Problem**: Redaction takes too long

**Solution**:
- Lower DPI (150-200 for faster processing)
- Upgrade to GPU hardware
- Optimize batch processing

### Model Download Issues

**Problem**: Model fails to download

**Solution**:
- Check HuggingFace model availability
- Verify internet access in Space
- Pre-download model and include in Docker image

## Updating Your Space

To update your deployed API:

```bash
# Make changes locally
# Test changes

# Commit and push
git add .
git commit -m "Update: description of changes"
git push

# HuggingFace will automatically rebuild
```

## Cost Estimation

### Free Tier
- CPU Basic
- Limited to 2 CPU cores
- 16GB RAM
- Good for: Testing, low-traffic demos

### Paid Tiers
- CPU Upgrade: ~$0.50/hour (~$360/month if always on)
- GPU T4: ~$0.60/hour (~$432/month)
- GPU A10G: ~$1.50/hour (~$1,080/month)

**Recommendation**: Start with free tier, upgrade based on usage

## Alternative Deployment Options

### 1. Deploy on Your Own Server

```bash
# Build Docker image
docker build -t pdf-redaction-api .

# Run container
docker run -p 7860:7860 pdf-redaction-api
```

### 2. Deploy on Cloud Platforms

- **AWS ECS/Fargate**: For scalable production
- **Google Cloud Run**: Serverless container deployment
- **Azure Container Instances**: Easy container deployment
- **DigitalOcean App Platform**: Simple PaaS deployment

### 3. Deploy on Render.com

1. Connect your GitHub repo
2. Select "Docker" as environment
3. Deploy automatically

## Support

For issues:
1. Check HuggingFace Spaces documentation
2. Review logs in Space dashboard
3. Test locally with Docker first
4. Open issue on your repository

## Next Steps

After successful deployment:

1. ✅ Test all API endpoints
2. ✅ Set up monitoring
3. ✅ Configure custom domain (optional)
4. ✅ Add authentication for production
5. ✅ Implement rate limiting
6. ✅ Set up error tracking (e.g., Sentry)
7. ✅ Create API documentation with examples
8. ✅ Add usage analytics

Your API is now live and ready to use! 🚀