| # HuggingFace Deployment Checklist |
|
|
| Use this checklist to ensure your project is fully prepared for deployment to HuggingFace Spaces. |
|
|
| ## Pre-Deployment Checks |
|
|
| ### ✅ Code & Configuration |
| - [ ] `app.py` exists and has correct entry point |
| - [ ] `requirements.txt` is updated with all dependencies |
| - [ ] `src/main.py` has proper type annotations for Gradio compatibility |
| - [ ] `spaces.yaml` is configured for your resource needs |
| - [ ] `.gitignore` includes common Python ignore patterns |
| - [ ] `.gitattributes` has LFS configuration for `.pth` files |
|
|
| ### ✅ Documentation |
| - [ ] `README.md` has HuggingFace Space headers (title, emoji, sdk, python_version, app_file) |
| - [ ] `README.md` includes usage instructions and feature descriptions |
| - [ ] `DEPLOYMENT.md` provides comprehensive deployment guide |
| - [ ] `.env.example` shows available environment variables |
| - [ ] `LICENSE` file is present (MIT recommended for open-source) |
|
|
| ### ✅ Model & Data Files |
| - [ ] Model weights directory: `data/weights/TO_BE_USED/` exists |
| - [ ] At least one model file found and accessible (*.pth files) |
| - [ ] Preprocessing data files exist: `data/preprocess_data/` with: |
| - [ ] `label_encoder_pad_20.pickle` |
| - [ ] `ohe_pad_20.pickle` |
| - [ ] `scaler_pad_20.pickle` |
| - [ ] Total project size < 25 GB (HF Spaces limit) |
| - [ ] `.pth` files tracked with Git LFS in `.gitattributes` |
| |
| ### ✅ Dependencies |
| - [ ] PyTorch version is specified (torch==2.4.1) |
| - [ ] Gradio version is compatible (gradio==4.44.1) |
| - [ ] All imports in code are in `requirements.txt` |
| - [ ] No local-only dependencies or custom packages |
| - [ ] `opencv-python-headless` used instead of `opencv-python` (for headless servers) |
| |
| ### ✅ Code Quality |
| - [ ] No hardcoded local paths (use `os.path` relative paths) |
| - [ ] No local file system access outside of project directory |
| - [ ] No network calls to external APIs that require authentication |
| - [ ] Proper error handling for missing model files |
| - [ ] App handles gracefully when run on CPU-only systems |
| |
| ### ✅ Performance |
| - [ ] Model loading is lazy (not at import/startup time) |
| - [ ] Model caching implemented to avoid reloading |
| - [ ] Queue enabled in Gradio for concurrent request handling |
| - [ ] Gradio version supports queue() method |
| |
| ### ✅ Git & Version Control |
| - [ ] Project is a Git repository (`git init` if needed) |
| - [ ] Remote added for HuggingFace: `git remote add origin https://huggingface.co/spaces/<user>/<space>` |
| - [ ] All source files are tracked: `git add .` |
| - [ ] Initial commit created: `git commit -m "Initial commit"` |
| - [ ] No `.git/config` with wrong remote URL |
| |
| ### ✅ HuggingFace Account Setup |
| - [ ] HuggingFace account created and verified |
| - [ ] Git credentials configured: `huggingface-cli login` |
| - [ ] SSH keys set up (if using SSH) or token saved |
| - [ ] Write access to target Space confirmed |
| |
| ## Deployment Steps |
| |
| 1. **Create Space on HuggingFace** |
| - [ ] Go to https://huggingface.co/new |
| - [ ] Name: `skin-lesion-explainability` (or preferred name) |
| - [ ] Type: **Space** (not Model or Dataset) |
| - [ ] SDK: **Gradio** |
| - [ ] Python Version: **3.10** |
| - [ ] Visibility: **Public** (or Private) |
| |
| 2. **Clone & Configure** |
| ```bash |
| [ ] git clone https://huggingface.co/spaces/<username>/<space-name> |
| [ ] cp -r /path/to/project/* . |
| [ ] cd <space-name> |
| ``` |
| |
| 3. **Verify Files** |
| ```bash |
| [ ] ls -la app.py |
| [ ] ls -la requirements.txt |
| [ ] ls -la README.md |
| [ ] ls -la spaces.yaml |
| [ ] ls -la src/ |
| [ ] ls -la data/ |
| ``` |
| |
| 4. **Push to HuggingFace** |
| ```bash |
| [ ] git add . |
| [ ] git commit -m "Initial deployment" |
| [ ] git push origin main |
| ``` |
| |
| 5. **Monitor Build** |
| - [ ] Go to https://huggingface.co/spaces/<username>/<space-name> |
| - [ ] Check "Runtime" tab for build status |
| - [ ] Watch logs for errors |
| - [ ] Wait for "Running" status |
| |
| ## Post-Deployment Verification |
| |
| ### ✅ Functional Testing |
| - [ ] App loads without errors (check Logs tab) |
| - [ ] Gradio interface appears in browser |
| - [ ] All input fields render correctly |
| - [ ] Model dropdown populated with choices |
| - [ ] Can select metadata groups |
| - [ ] Image upload works |
| |
| ### ✅ Feature Testing |
| - [ ] Upload test image succeeds |
| - [ ] Model inference completes (~30 sec first run, 5-15 sec cached) |
| - [ ] Attention heatmap generates correctly |
| - [ ] Metadata CSV preview displays |
| - [ ] Clear button resets all fields |
| - [ ] No errors in browser console (F12 to check) |
| |
| ### ✅ Performance Monitoring |
| - [ ] First inference: 30-60 seconds (acceptable with model loading) |
| - [ ] Subsequent inferences: 5-15 seconds |
| - [ ] Queue works with concurrent requests (if multiple users) |
| - [ ] Memory usage stable (check Runtime/Logs) |
| |
| ## Troubleshooting Guide |
| |
| ### Build Fails with ImportError |
| **Solution**: |
| 1. Check `requirements.txt` - ensure all imports are listed |
| 2. Read full error in Logs tab |
| 3. Verify Python 3.10 is specified in `spaces.yaml` |
| |
| ### Models Not Found at Runtime |
| **Solution**: |
| 1. Verify `data/weights/TO_BE_USED/` directory in repository |
| 2. Check file sizes in Logs during startup |
| 3. Ensure `.pth` files are fetched (Git LFS resolution) |
| |
| ### CUDA Out of Memory |
| **Solution**: |
| 1. Add to `spaces.yaml`: `gpu: "A10G"` |
| 2. Or remove GPU line for CPU-only |
| 3. Set env var: `PYTORCH_CUDA_PER_PROCESS_MEMORY_FRACTION=0.5` |
| |
| ### App Loads but Inference Fails |
| **Solution**: |
| 1. Check browser console for errors (F12) |
| 2. Check Logs tab for Python errors |
| 3. Verify all preprocessing files exist in `data/preprocess_data/` |
| |
| ## Optimization Tips |
| |
| ### Speed Up First Inference |
| - Pin GPU instance in `spaces.yaml` (if budget allows) |
| - Pre-load one model at startup (modify `inference.py`) |
| |
| ### Reduce Memory Usage |
| - Use CPU-only mode (remove gpu line in spaces.yaml) |
| - Quantize models (advanced) |
| |
| ### Handle More Concurrent Users |
| - Increase `GRADIO_QUEUE_SIZE` in environment |
| - Add GPU for faster inference |
| - Implement request timeout |
| |
| ## Security Considerations |
| |
| - [ ] No API keys/secrets in code |
| - [ ] Use `.env.example` for configuration templates |
| - [ ] Avoid downloading from untrusted sources |
| - [ ] Review third-party packages for vulnerabilities |
| - [ ] Model predictions should not persist user data |
| |
| ## Documentation |
| |
| - [ ] README.md has clear feature description |
| - [ ] DEPLOYMENT.md has step-by-step guide |
| - [ ] Code includes docstrings (especially inference.py) |
| - [ ] Comments explain non-obvious logic |
| - [ ] Example outputs shown in README |
| |
| ## Final Checklist |
| |
| - [ ] All items above are checked |
| - [ ] Tested locally: `python app.py` works |
| - [ ] Committed to git: `git status` shows clean |
| - [ ] Pushed to HuggingFace: `git push origin main` |
| - [ ] Build completed: Space shows "Running" status |
| - [ ] App functional: Can upload, select options, generate predictions |
| - [ ] Performance adequate: Inference completes in reasonable time |
| - [ ] Logs clean: No errors in Logs tab |
| |
| ## Support Resources |
| |
| - **HuggingFace Spaces Docs**: https://huggingface.co/docs/hub/spaces |
| - **Gradio Documentation**: https://gradio.app/docs |
| - **PyTorch Hub**: https://pytorch.org/hub/ |
| - **Community Forum**: https://discuss.huggingface.co/ |
| |
| --- |
| |
| **Status**: ⏳ Ready to Deploy (after checking all boxes) |
| |
| **Last Verified**: March 2026 |
| |
