DEPLOYMENT.md

# 🚀 Deploying Devam Jersey Server to Hugging Face Spaces

This guide will help you deploy your jersey similarity detection server to Hugging Face Spaces.

## 📋 Prerequisites

1. **Hugging Face Account**: Sign up at [huggingface.co](https://huggingface.co)
2. **Git**: Ensure git is installed and configured
3. **Python Environment**: Python 3.9+ with pip

## 🎯 Quick Start

### Option 1: Web Interface (Recommended)

1. **Go to Hugging Face Spaces**
   - Visit [https://huggingface.co/spaces](https://huggingface.co/spaces)
   - Click "Create new Space"

2. **Configure Your Space**
   - **Owner**: Your username
   - **Space name**: `devam-jersey-server` (or your preferred name)
   - **SDK**: Select **Docker**
   - **License**: Choose appropriate license
   - **Visibility**: Public or Private
   - Click "Create Space"

3. **Upload Your Files**
   - In your new space, click "Files and versions"
   - Upload all project files:
     - `inference_server.py`
     - `requirements.txt`
     - `Dockerfile`
     - `README.md`
     - `models/deepfashion2_yolov8s-seg.pt`
     - `index/jersey_metadata.npy`
     - Any other necessary files

4. **Monitor Build**
   - Go to "Settings" → "Build logs"
   - Wait for the Docker build to complete
   - Your API will be available at `https://YOUR_USERNAME-devam-jersey-server.hf.space`

### Option 2: Git Clone Method

1. **Clone the Created Space**
   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/devam-jersey-server
   cd devam-jersey-server
   ```

2. **Copy Your Project Files**
   ```bash
   # Copy all your project files to this directory
   cp -r /path/to/your/project/* .
   ```

3. **Commit and Push**
   ```bash
   git add .
   git commit -m "Initial upload of Devam Jersey Server"
   git push
   ```

### Option 3: CLI Method

1. **Install huggingface_hub**
   ```bash
   pip install huggingface_hub
   ```

2. **Create Space via CLI**
   ```bash
   huggingface-cli repo create devam-jersey-server --type space --space-sdk docker
   ```

3. **Clone and Upload**
   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/devam-jersey-server
   cd devam-jersey-server
   # Copy files and push as in Option 2
   ```

## 🔧 Configuration

### Environment Variables (Optional)

In your Space settings, you can add environment variables:

- `MODEL_PATH`: Path to your YOLO model
- `INDEX_PATH`: Path to your FAISS index
- `DEVICE`: `cuda` or `cpu`

### Hardware Requirements

- **CPU**: Basic CPU is sufficient for testing
- **GPU**: For production use, consider upgrading to GPU-enabled space
- **Memory**: At least 4GB RAM recommended

## 🧪 Testing Your Deployment

### 1. Check Space Status
- Visit your space URL
- Check the "Logs" tab for any errors
- Verify the API is responding

### 2. Test Endpoints
```bash
# Test root endpoint
curl https://YOUR_USERNAME-devam-jersey-server.hf.space/

# Test DINO endpoint (upload an image)
curl -X POST https://YOUR_USERNAME-devam-jersey-server.hf.space/dino \
  -F "file=@test_image.jpg"

# Test FAISS endpoint
curl -X POST https://YOUR_USERNAME-devam-jersey-server.hf.space/faiss \
  -H "Content-Type: application/json" \
  -d '{"features": [0.1, 0.2, ...]}'
```

### 3. Use the Test Script
```bash
# Update the base_url in test_server.py
python test_server.py
```

## 🚨 Troubleshooting

### Common Issues

1. **Build Fails**
   - Check Dockerfile syntax
   - Verify all files are uploaded
   - Check build logs for specific errors

2. **Model Loading Errors**
   - Ensure model files are properly uploaded
   - Check file paths in code
   - Verify model file integrity

3. **Memory Issues**
   - Consider using smaller models
   - Optimize Docker image
   - Upgrade to GPU space if needed

4. **API Not Responding**
   - Check space status
   - Verify port configuration (should be 7860)
   - Check logs for runtime errors

### 🐳 Docker Build Issues

#### Package Installation Errors
If you encounter errors like:
```
Package 'libgl1-mesa-glx' is not available
```

**Solution 1**: Use the updated Dockerfile with minimal dependencies
**Solution 2**: Try the alternative Dockerfile:
```bash
# Rename the alternative Dockerfile
mv Dockerfile Dockerfile.backup
mv Dockerfile.alternative Dockerfile
git add .
git commit -m "Use alternative Dockerfile for compatibility"
git push
```

**Solution 3**: Use a different base image in your Dockerfile:
```dockerfile
FROM python:3.9-bullseye
# or
FROM python:3.9-buster
```

#### OpenCV Compatibility Issues
If OpenCV fails to install or work:
- The project now uses `opencv-python-headless` which is more Docker-friendly
- This version doesn't require GUI libraries

### Debug Commands

```bash
# Check space logs
# Go to Settings → Logs in your HF Space

# Test locally first
python inference_server.py
python test_server.py

# Check Docker build locally
docker build -t devam-jersey .
docker run -p 7860:7860 devam-jersey
```

## 📊 Monitoring

- **Build Logs**: Check after each push
- **Runtime Logs**: Monitor for errors during operation
- **Space Analytics**: Track usage and performance
- **API Status**: Verify endpoints are responding

## 🔄 Updates

To update your deployed space:

1. **Make Changes Locally**
2. **Push to Git**
   ```bash
   git add .
   git commit -m "Update description"
   git push
   ```
3. **Monitor Build**: Check build logs for success
4. **Test**: Verify changes work as expected

## 📚 Additional Resources

- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Docker on HF Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)

## 🎉 Success!

Once deployed, your jersey similarity server will be available at:
```
https://YOUR_USERNAME-devam-jersey-server.hf.space
```

Share this URL with others to use your API!

---

**Need Help?** Check the [Hugging Face Community](https://huggingface.co/forums) for support.