Add a markdown note for HF deployment

docs/HUGGINGFACE_DEPLOYMENT.md

@@ -0,0 +1,309 @@
+# Hosting on Hugging Face Spaces
+
+This guide covers deploying the Brain Lesion Segmentation web app (VTK.js frontend + FastAPI backend) to Hugging Face Spaces.
+
+---
+
+## Recommended: Docker Space (Full-Stack)
+
+For your VTK.js frontend + FastAPI backend architecture, the best approach is a **Docker Space**. This bundles both your FastAPI backend and static frontend in one deployment.
+
+### Why Docker Space?
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Docker Space** ✅ | Full control, GPU support, single deployment | Requires Dockerfile |
+| Gradio Space | Simple setup | Not suitable for custom JS frontend |
+| Static Space | Free, fast CDN | No backend/API support |
+
+---
+
+## Step-by-Step Deployment
+
+### 1. Create a Dockerfile
+
+Create `Dockerfile` in your project root:
+
+```dockerfile
+# Dockerfile
+FROM python:3.10-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Hugging Face Spaces expects port 7860
+EXPOSE 7860
+
+# Start FastAPI serving both API and static files
+CMD ["uvicorn", "seg_app.backend.api:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+### 2. Update FastAPI to Serve Static Frontend
+
+Add the following to `seg_app/backend/api.py` (at the END of the file, after all API routes):
+
+```python
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+import os
+
+# Serve static files for VTK.js slicer UI
+static_dir = os.path.join(os.path.dirname(__file__), "..", "ui_slicer")
+app.mount("/slicer", StaticFiles(directory=static_dir, html=True), name="slicer")
+
+# Root redirect to slicer UI
+@app.get("/")
+async def root():
+    return FileResponse(os.path.join(static_dir, "index.html"))
+```
+
+### 3. Update Frontend API URL
+
+In `seg_app/ui_slicer/api-client.js`, update the base URL to work in both local and production:
+
+```javascript
+class ApiClient {
+    constructor() {
+        // Use same origin in production, localhost for development
+        this.baseUrl = window.location.hostname === 'localhost' 
+            ? 'http://localhost:8000'
+            : window.location.origin;
+    }
+    // ... rest of the class
+}
+```
+
+### 4. Update README.md with HF Spaces Metadata
+
+Add YAML frontmatter to the top of your `README.md`:
+
+```yaml
+---
+title: Brain Lesion Segmentation
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# Brain Lesion Segmentation Tool
+... (rest of your README)
+```
+
+### 5. Create .dockerignore
+
+Create `.dockerignore` to exclude unnecessary files:
+
+```
+__pycache__/
+*.pyc
+*.pyo
+.git/
+.gitignore
+*.md
+!README.md
+.env
+.vscode/
+*.ipynb
+test_*.py
+```
+
+### 6. Deploy to Hugging Face
+
+#### Option A: Using HF CLI
+
+```bash
+# Install Hugging Face CLI
+pip install huggingface_hub
+
+# Login to Hugging Face
+huggingface-cli login
+
+# Create a new Space
+huggingface-cli repo create YOUR_USERNAME/brain-lesion-seg --type space --space_sdk docker
+
+# Add HF as remote and push
+git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/brain-lesion-seg
+git push hf main
+```
+
+#### Option B: Using Web Interface
+
+1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+2. Select **Docker** as the SDK
+3. Choose a hardware tier (see recommendations below)
+4. Upload files or connect your GitHub repo
+
+---
+
+## Hardware Recommendations
+
+| Tier | Cost | RAM | Best For |
+|------|------|-----|----------|
+| **CPU Basic** (free) | $0 | 16GB | Testing, demos |
+| **CPU Upgrade** | ~$0.03/hr | 32GB | Small volumes |
+| **T4 Small** ✅ | ~$0.60/hr | 16GB + GPU | SAM-Med3D, nnUNet |
+| **T4 Medium** | ~$0.90/hr | 32GB + GPU | Large volumes |
+| **A10G Small** | ~$1.50/hr | 24GB VRAM | Fast inference |
+
+**Recommendation**: Start with **CPU Basic** for testing, upgrade to **T4 Small** for GPU inference with deep learning models.
+
+---
+
+## Environment Variables & Secrets
+
+For sensitive configuration (model paths, API keys), use HF Spaces Secrets:
+
+1. Go to Space Settings → Repository secrets
+2. Add secrets like:
+   - `HF_TOKEN` (if loading private models)
+   - `MODEL_PATH` (custom model locations)
+
+Access in Python:
+```python
+import os
+hf_token = os.environ.get("HF_TOKEN")
+```
+
+---
+
+## GPU Support for Deep Learning Models
+
+If using SAM-Med3D or nnUNet, ensure GPU support:
+
+### Update Dockerfile for GPU:
+
+```dockerfile
+FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime
+
+# ... rest of Dockerfile
+```
+
+### Update requirements.txt:
+
+```
+torch>=2.0.0
+monai>=1.3.0
+nnunetv2>=2.2
+# ... other dependencies
+```
+
+---
+
+## Troubleshooting
+
+### Build Fails
+
+Check the build logs in your Space's "Logs" tab. Common issues:
+- Missing system dependencies → Add to `apt-get install`
+- Python package conflicts → Pin versions in requirements.txt
+
+### App Not Loading
+
+- Ensure port 7860 is exposed and used
+- Check that static files are correctly mounted
+- Verify API routes don't conflict with static file routes
+
+### Slow Inference
+
+- Upgrade to GPU hardware tier
+- Enable model caching (load once, reuse)
+- Consider model quantization for faster inference
+
+### CORS Issues
+
+If frontend/backend are on different origins, add CORS middleware:
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Or specify your frontend URL
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+---
+
+## Local Testing with Docker
+
+Before deploying, test locally:
+
+```bash
+# Build the image
+docker build -t brain-seg-app .
+
+# Run the container
+docker run -p 7860:7860 brain-seg-app
+
+# Open in browser
+# http://localhost:7860
+```
+
+---
+
+## File Structure for Deployment
+
+```
+web_app/
+├── Dockerfile              # Container definition
+├── .dockerignore           # Exclude unnecessary files
+├── README.md               # With HF YAML frontmatter
+├── requirements.txt        # Python dependencies
+├── seg_app/
+│   ├── backend/
+│   │   └── api.py          # FastAPI + static file serving
+│   ├── ui_slicer/
+│   │   ├── index.html      # VTK.js frontend
+│   │   ├── app.js
+│   │   ├── api-client.js   # Updated for production URLs
+│   │   └── ...
+│   └── models/
+│       └── ...
+```
+
+---
+
+## Alternative: Split Deployment
+
+For more flexibility, deploy frontend and backend separately:
+
+| Component | Space Type | URL |
+|-----------|------------|-----|
+| Frontend | Static Space (free) | `your-user/brain-seg-frontend` |
+| Backend | Docker Space (GPU) | `your-user/brain-seg-api` |
+
+This allows:
+- Free hosting for static files
+- GPU only when needed for inference
+- Independent scaling
+
+Configure the frontend to point to the backend API URL.
+
+---
+
+## Useful Links
+
+- [HF Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [Docker Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [Spaces GPU Guide](https://huggingface.co/docs/hub/spaces-gpus)
+- [Secrets & Environment Variables](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)