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

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:

# 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

# 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

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

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:

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:

# 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

# 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! 🚀