DEPLOYMENT.md

# Deployment Guide - Hugging Face Spaces

## Quick Deployment to Hugging Face

### Step 1: Prepare Files

Ensure you have these files:
```
your-repo/
├── app.py                    # FastAPI application
├── binary_segmentation.py    # Core segmentation module
├── requirements.txt          # Python dependencies
├── Dockerfile               # Docker configuration
├── README.md                # This becomes your Space README
├── static/
│   └── index.html          # Web interface
└── .model_cache/
    └── u2netp.pth          # Model weights (IMPORTANT!)
```

### Step 2: Download U2NETP Weights

**CRITICAL**: You must download the U2NETP model weights:

1. Visit: https://github.com/xuebinqin/U-2-Net/tree/master/saved_models
2. Download: `u2netp.pth` (4.7 MB)
3. Place in: `.model_cache/u2netp.pth`

**OR** use this direct link:
```bash
mkdir -p .model_cache
wget https://github.com/xuebinqin/U-2-Net/raw/master/saved_models/u2netp/u2netp.pth -O .model_cache/u2netp.pth
```

### Step 3: Create Hugging Face Space

1. Go to https://huggingface.co/new-space
2. Fill in:
   - **Space name**: `background-removal` (or your choice)
   - **License**: Apache 2.0
   - **SDK**: Docker
   - **Hardware**: CPU Basic (free tier works!)
   
3. Click "Create Space"

### Step 4: Upload Files

#### Option A: Using Git (Recommended)

```bash
# Clone your new space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy all files
cp /path/to/app.py .
cp /path/to/binary_segmentation.py .
cp /path/to/requirements.txt .
cp /path/to/Dockerfile .
cp /path/to/README_HF.md ./README.md
cp -r /path/to/static .
cp -r /path/to/.model_cache .

# Commit and push
git add .
git commit -m "Initial commit"
git push
```

#### Option B: Using Web Interface

1. Click "Files" → "Add file"
2. Upload each file individually
3. **Important**: Upload `.model_cache/u2netp.pth` (it's large, ~4.7MB)

### Step 5: Wait for Build

- Space will build automatically (takes 3-5 minutes)
- Watch the "Logs" tab for build progress
- Once complete, your Space will be live!

### Step 6: Test Your Space

Visit your Space URL and try:
1. Upload an image
2. Click "Process Image"
3. Download the result

## Configuration Options

### Use Different Models

To enable BiRefNet or RMBG models, edit `requirements.txt`:

```txt
# Uncomment these lines:
transformers>=4.30.0
huggingface-hub>=0.16.0
```

**Note**: These models are larger and may require upgraded hardware (GPU).

### Custom Port

Default port is 7860 (Hugging Face standard). To change:

In `Dockerfile`:
```dockerfile
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
```

### Environment Variables

Add secrets in Space Settings:
```python
import os
API_KEY = os.environ.get("API_KEY", "default")
```

## Hardware Requirements

### CPU Basic (Free)
- ✅ U2NETP model
- ✅ Small to medium images (<5MP)
- ⏱️ ~2-5 seconds per image

### CPU Upgrade
- ✅ U2NETP model
- ✅ Large images
- ⏱️ ~1-3 seconds per image

### GPU T4
- ✅ All models (U2NETP, BiRefNet, RMBG)
- ✅ Any image size
- ⏱️ <1 second per image

## Troubleshooting

### Build Fails

**Issue**: "No module named 'binary_segmentation'"
- **Fix**: Ensure `binary_segmentation.py` is in root directory

**Issue**: "Model weights not found"
- **Fix**: Upload `u2netp.pth` to `.model_cache/u2netp.pth`

**Issue**: "OpenCV error"
- **Fix**: Check Dockerfile has `libgl1-mesa-glx` installed

### Runtime Errors

**Issue**: "Out of memory"
- **Fix**: Upgrade to GPU hardware OR reduce image size

**Issue**: "Slow processing"
- **Fix**: Use CPU Upgrade or GPU hardware

**Issue**: "Model not loading"
- **Fix**: Check logs, ensure model file is in correct location

### API Not Working

**Issue**: 404 errors
- **Fix**: Check that FastAPI routes are correct
- **Fix**: Ensure `app:app` in CMD matches `app = FastAPI()` in code

**Issue**: CORS errors
- **Fix**: CORS is enabled by default; check browser console

## File Structure Verification

Before deploying, verify:

```bash
# Check all files exist
ls -la

# Should see:
# app.py
# binary_segmentation.py
# requirements.txt
# Dockerfile
# README.md
# static/index.html
# .model_cache/u2netp.pth

# Check model file size (should be ~4.7MB)
ls -lh .model_cache/u2netp.pth
```

## Alternative: Deploy Without Docker

If you prefer not to use Docker, create `.spacesdk` file:

```
sdk: gradio
sdk_version: 4.0.0
```

Then modify to use Gradio instead of FastAPI. But Docker is recommended for FastAPI.

## Post-Deployment

### Monitor Usage
- Check "Analytics" tab for usage stats
- Monitor "Logs" for errors

### Update Your Space
```bash
git pull
# Make changes
git add .
git commit -m "Update"
git push
```

### Share Your Space
- Get shareable link from Space page
- Embed in website using iframe
- Use API endpoint in your apps

## Example API Usage from External Apps

Once deployed, use your Space API:

```python
import requests

SPACE_URL = "https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME"

with open('image.jpg', 'rb') as f:
    response = requests.post(
        f"{SPACE_URL}/segment",
        files={'file': f},
        data={'model': 'u2netp', 'threshold': 0.5}
    )
    
with open('result.png', 'wb') as out:
    out.write(response.content)
```

## Need Help?

- Hugging Face Docs: https://huggingface.co/docs/hub/spaces
- Community Forum: https://discuss.huggingface.co/
- Discord: https://discord.gg/hugging-face

---

**Pro Tip**: Start with CPU Basic (free), test your Space, then upgrade to GPU if needed!