# VREyeSAM - Hugging Face Spaces Deployment Guide

## 🚀 Quick Start Deployment

Follow these steps to deploy VREyeSAM to Hugging Face Spaces with full security.

## Step 1: Prepare Your Repository

### Verify Security Setup
```bash
# Check no model weights are committed
git status
git ls-files | grep -E '\.(pt|pth|torch|bin)$'
# Should output nothing!

# Verify .gitignore is properly configured
cat .gitignore | grep -E '(\.pt|\.torch|checkpoints)'
```

### Remove Unnecessary Files
- ✅ Markdown documentation files removed
- ✅ Model server created for secure inference
- ✅ Path handling secured in model_server.py

## Step 2: Create HuggingFace Space

1. Navigate to: https://huggingface.co/spaces
2. Click **"Create new Space"**
3. Fill in:
   ```
   Space name: vreyesam
   License: MIT  
   SDK: Docker
   Visibility: Public (code is public, weights are private)
   ```

## Step 3: Upload Files to Space

Choose one of the following methods:

### Method A: Git Push (Recommended)
```bash
# Clone the space
git clone https://huggingface.co/spaces/YOUR_USERNAME/vreyesam
cd vreyesam

# Copy your project files
cp /path/to/your/vreyesam/* .

# Push to space
git add .
git commit -m "Deploy VREyeSAM with security"
git push
```

### Method B: Web Upload
1. Go to space settings
2. Use the file manager to upload:
   - `app.py`
   - `model_server.py`
   - `requirements_deploy.txt`
   - `Dockerfile`
   - `.streamlit/config.toml` (if exists)
   - `README.md`
   - `SECURITY.md`

## Step 4: Configure Secrets (For Private Weights)

1. Go to space **Settings**
2. Add **Repository secrets**:
   - `HF_TOKEN`: Your HuggingFace API token (from https://huggingface.co/settings/tokens)

The Dockerfile will automatically use this to download weights.

## Step 5: Set Webhooks (Optional)

For automatic updates when code changes:

1. Create your code repository (GitHub, GitLab, etc.)
2. In space Settings → Webhooks
3. Add webhook from your repo
4. Now pushes to your repo → automatic space update

## Step 6: Verify Deployment

Once Docker builds complete (5-10 minutes):

1. Click "App" tab to see your running Spaces app
2. Test upload an iris image
3. Verify segmentation works
4. Download results

## 🔒 Security Verification

### Check These in Your Space:

```bash
# 1. Verify weights are downloaded at startup, not committed
# Check space README - should see "Model initialized" log

# 2. Try accessing checkpoint files directly
# Should get 404 or permission denied

# 3. Examine source code 
# model.pt, .torch files should NOT appear in file listing

# 4. Check Docker logs
# Should NOT show full paths to checkpoints
```

## 📋 File Structure Expected in Space

```
vreyesam/
├── app.py                    # Streamlit app
├── model_server.py          # Secure model wrapper
├── Dockerfile               # Container definition
├── requirements_deploy.txt  # Python dependencies
├── README.md               # Public documentation
├── SECURITY.md             # Security guide
├── .gitignore              # Git ignore rules
├── .env.example            # Configuration template
└── .streamlit/
    └── config.toml         # Streamlit config
```

Model weights (checkpoint files) should NOT appear here - they're downloaded during build.

## 🛠️ Troubleshooting Deployment

### Weights Not Loading
- Check HF_TOKEN is set in secrets
- Verify weights URL in Dockerfile is correct
- Check space logs for download errors

### Build Timeout
- Increase timeout in space settings
- Pre-build Docker image and push to registry instead

### Models Not Segmenting
- Check error messages in app
- Verify config paths in model_server.py
- Check GPU availability: should fall back to CPU

### Size Limit Issues
- Hugging Face Spaces have a 50GB storage limit
- Model weights typically 5-7GB total
- Should be sufficient for most deployments

## 🚀 Advanced: Set Up CI/CD

### GitHub Actions Example
```yaml
name: Deploy to HF Spaces
on:
  push:
    branches: [main]
    
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Push to Spaces
        run: |
          git config user.email "your-email@example.com"
          git config user.name "Your Name"
          git remote add space https://${{ secrets.HF_USERNAME }}:${{ secrets.HF_TOKEN }}@huggingface.co/spaces/${{ secrets.HF_USERNAME }}/vreyesam
          git push -f space HEAD:main
```

## 📞 Support & Monitoring

- **Check Logs**: Space Settings → Logs
- **Monitor Health**: Space card shows if running
- **Error Tracking**: Streamlit errors appear in browser inspector + logs
- **Performance**: Use HF Space hardware settings to allocate GPU if needed

## Important Notes

⚠️ **DO NOT:**
- Commit `segment-anything-2/checkpoints/` to git
- Push `.env` files with tokens
- Share HF_TOKEN outside of space secrets

✅ **DO:**
- Keep code repository public
- Share README and SECURITY guide
- Use HF Spaces secrets for tokens
- Document your deployment

---

## Next Steps

1. [ ] Prepare repository files
2. [ ] Verify .gitignore is correct  
3. [ ] Create Hugging Face Space
4. [ ] Upload/push code files
5. [ ] Set HF_TOKEN in secrets
6. [ ] Wait for Docker build (5-10 min)
7. [ ] Test the deployed app
8. [ ] Share your space link!

**Congratulations! Your model is now securely deployed.** 🎉

---

For questions: Check SECURITY.md or contact geetanjalisharma546@gmail.com