hardbanrecords/Metadata-Engine

1# Hugging Face Spaces Deployment Guide2# Music Metadata Engine - Complete Instructions3 4## 📋 Prerequisites5 61. **Hugging Face Account** with Pro subscription (for Docker Spaces)72. **Git** installed locally83. **Hugging Face CLI** (optional but recommended):9   ```bash10   pip install huggingface_hub11   huggingface-cli login12   ```13 14---15 16## 🚀 Step-by-Step Deployment17 18### 1. Create New Space on Hugging Face19 201. Go to: https://huggingface.co/new-space212. Fill in:22   - **Owner**: Your username/organization23   - **Space name**: `music-metadata-engine`24   - **License**: **other** (Proprietary / HardbanRecords Lab)25   - **SDK**: **Docker**26   - **Space Hardware**: **CPU Basic** (Free) or **CPU Upgrade** (for faster processing)27 283. Click "Create Space"29 30---31 32### 2. Clone the Repository33 34```bash35# Clone your new HF Space36git clone https://huggingface.co/spaces/YOUR_USERNAME/music-metadata-engine37cd music-metadata-engine38 39# Add your local project as remote40git remote add local E:/Music-Metadata-Engine41git pull local main --allow-unrelated-histories42```43 44---45 46### 3. Verify Required Files47 48Ensure these files exist in the root:49 50```51music-metadata-engine/52├── Dockerfile                 ✅ Multi-stage build53├── README.md                  ✅ HF frontmatter + docs54├── .dockerignore              ✅ Build optimization55├── backend/56│   ├── app/57│   ├── requirements.txt       ✅58│   └── .env.example           ❗ Create this59└── frontend/60    ├── package.json           ✅61    └── ...62```63 64---65 66### 4. Configure Environment Variables67 68#### Option A: HF Spaces Secrets (Recommended)69 701. Go to your Space settings: `https://huggingface.co/spaces/YOUR_USERNAME/music-metadata-engine/settings`712. Scroll to **"Repository secrets"**723. Add required secrets:73 74```75GEMINI_API_KEY=your_gemini_api_key_here76PINATA_JWT=your_pinata_jwt_here77PINATA_GATEWAY=https://gateway.pinata.cloud/ipfs/78```79 80Optional secrets:81```82GROQ_API_KEY=your_groq_key83SPOTIFY_CLIENT_ID=your_spotify_id84SPOTIFY_CLIENT_SECRET=your_spotify_secret85LASTFM_API_KEY=your_lastfm_key86```87 88#### Option B: .env file (Not recommended for production)89 90Create `backend/.env`:91```bash92GEMINI_API_KEY=your_key93PINATA_JWT=your_jwt94PINATA_GATEWAY=https://gateway.pinata.cloud/ipfs/95```96 97---98 99### 5. Push to Hugging Face100 101```bash102# Stage all files103git add .104 105# Commit106git commit -m "Initial deployment: Music Metadata Engine v2.1.0"107 108# Push to HF Space109git push origin main110```111 112---113 114### 6. Monitor Build115 1161. Go to your Space: `https://huggingface.co/spaces/YOUR_USERNAME/music-metadata-engine`1172. Click **"Logs"** tab1183. Wait for Docker build (~10-15 minutes first time)119 120Expected log output:121```122[Stage 1/2] Building frontend...123[Stage 2/2] Installing Python dependencies...124Successfully built music-metadata-engine125Container started on port 7860126✅ Serving frontend from: /home/user/app/frontend/dist127```128 129---130 131### 7. Verify Deployment132 133Once build completes:134 1351. **Frontend**: Visit your Space URL136   - Should show Music Metadata Engine UI137   - Test file upload138 1392. **Backend API**: Visit `/docs`140   - Should show FastAPI Swagger UI141   - Test `/` endpoint (should return `{"status": "MME Worker Online"}`)142 1433. **Health Check**:144   ```bash145   curl https://YOUR_USERNAME-music-metadata-engine.hf.space/146   ```147 148---149 150## 🔧 Troubleshooting151 152### Build Fails153 154**Error**: `COPY failed: file not found`155- **Fix**: Check `.dockerignore` isn't excluding necessary files156 157**Error**: `npm ERR! code ELIFECYCLE`158- **Fix**: Delete `frontend/node_modules` and `frontend/package-lock.json`, recommit159 160**Error**: `ModuleNotFoundError: No module named 'essentia'`161- **Fix**: Ensure `essentia-tensorflow` is in `backend/requirements.txt`162 163### Runtime Errors164 165**Error**: `Frontend build not found`166- **Fix**: Check Dockerfile COPY path for frontend/dist167 168**Error**: `GEMINI_API_KEY not found`169- **Fix**: Add secret in Space settings (see Step 4)170 171**Error**: `Port 7860 already in use`172- **Fix**: HF handles this automatically, restart Space if needed173 174### Performance Issues175 176**Slow analysis (>2 minutes)**177- **Solution**: Upgrade to **CPU Upgrade** hardware ($9/month)178- **Alternative**: Use Groq instead of Gemini (set `GROQ_API_KEY`)179 180**Out of memory**181- **Solution**: Upgrade to **2 vCPU** or **4 vCPU** hardware182- **Alternative**: Reduce `max_concurrent` in `batch_processor.py` to 1183 184## 💎 HF Pro Optimization (Power User)185 186Jeśli używasz **Hugging Face Pro**, możesz znacząco przyspieszyć działanie aplikacji:187 188### 1. Persistent Storage (Trwałość Danych)189W ustawieniach Space włącz **Persistent Storage** (np. 20GB). 190*   Aplikacja automatycznie wykryje folder `/data` i tam przeniesie bazę danych SQLite.191*   Dzięki temu historia analiz i statusy zadań przetrwają restarty kontenera.192 193### 2. Większa Współbieżność (Batch Processing)194Przy hardware **CPU Upgrade** (8 vCPU), możesz zwiększyć liczbę analizowanych plików naraz:195Dodaj sekret (Environment Variable):196*   `BATCH_MAX_CONCURRENT`: `8` (domyślnie 3)197 198### 3. Skalowanie API199Opracowaliśmy system, który dynamicznie wykorzystuje moc obliczeniową:200*   Standardowo uvicorn działa na 1 workerze (oszczędność RAM).201*   Możesz to zmienić w `Dockerfile` zmieniając `--workers 1` na większą liczbę, jeśli planujesz obsługiwać wielu użytkowników jednocześnie na wersji Pro.202 203---204 205## 🎛️ Hardware Recommendations206 207| Hardware | vCPU | RAM | Price | Best For |208|----------|------|-----|-------|----------|209| CPU Basic | 2 | 16GB | Free | Testing, low traffic |210| CPU Upgrade | 4 | 32GB | $9/mo | Production, 10-50 users/day |211| T4 GPU (Small) | 4 | 15GB | $60/mo | Heavy AI, stem separation |212 213**Recommended**: **CPU Upgrade** (4 vCPU, 32GB RAM)214 215---216 217## 🔐 Security Best Practices218 2191. **Never commit API keys** to Git220   - Use HF Secrets exclusively221   - Add `.env` to `.gitignore`222 2232. **CORS Configuration**224   - Update `backend/app/main.py` line 49225   - Change `allow_origins=["*"]` to your domain:226     ```python227     allow_origins=["https://YOUR_USERNAME-music-metadata-engine.hf.space"]228     ```229 2303. **Rate Limiting**231   - Install `slowapi`:232     ```bash233     pip install slowapi234     ```235   - Add to `main.py`:236     ```python237     from slowapi import Limiter, _rate_limit_exceeded_handler238     from slowapi.util import get_remote_address239     240     limiter = Limiter(key_func=get_remote_address)241     app.state.limiter = limiter242     app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)243     244     @app.post("/analyze")245     @limiter.limit("10/hour")  # 10 requests per hour per IP246     async def analyze(...):247         ...248     ```249 250---251 252## 📊 Monitoring253 254### Built-in Metrics255 256Access at: `https://YOUR_USERNAME-music-metadata-engine.hf.space/metrics`257 258### Custom Logging259 260View real-time logs:2611. Go to Space → **Logs** tab2622. Filter by level (INFO, WARNING, ERROR)263 264### Uptime Monitoring265 266Use external service:267- **UptimeRobot**: https://uptimerobot.com268- **Pingdom**: https://pingdom.com269- Monitor endpoint: `https://YOUR_USERNAME-music-metadata-engine.hf.space/`270 271---272 273## 🔄 Updating the Space274 275### Push Updates276 277```bash278# Make changes locally279git add .280git commit -m "Update: feature XYZ"281git push origin main282```283 284HF will automatically rebuild and redeploy.285 286### Force Rebuild287 288If build is stuck:2891. Go to Space Settings2902. Click **"Factory reboot"**2913. Confirm292 293---294 295## 💰 Cost Estimation296 297| Component | Free Tier | Paid (Pro) |298|-----------|-----------|------------|299| HF Space (Basic) | ✅ Included | - |300| HF Space (Upgrade) | - | $9/mo |301| Gemini API | 15 RPM free | Pay-as-you-go |302| Pinata | 1GB free | $20/mo (100GB) |303| **Total (Basic)** | **$0/mo** | **~$9-30/mo** |304 305---306 307## 🎓 Advanced: Custom Domain308 3091. Get domain (e.g., `metadata.hardbanrecords.com`)3102. In Space Settings → **Custom Domain**3113. Add CNAME record in DNS:312   ```313   metadata.hardbanrecords.com → YOUR_USERNAME-music-metadata-engine.hf.space314   ```3154. Wait for SSL certificate (automatic)316 317---318 319## 📞 Support320 321**HF Spaces Issues**: https://huggingface.co/spaces/YOUR_USERNAME/music-metadata-engine/discussions322 323**Project Issues**: hardbanrecords@proton.me324 325---326 327## ✅ Deployment Checklist328 329- [ ] HF Space created with Docker SDK330- [ ] All files committed to Git331- [ ] Secrets configured (GEMINI_API_KEY, PINATA_JWT)332- [ ] Code pushed to HF333- [ ] Build completed successfully334- [ ] Frontend accessible335- [ ] API `/docs` working336- [ ] Test file analysis end-to-end337- [ ] CORS configured for production338- [ ] Rate limiting enabled339- [ ] Monitoring set up340 341---342 343**Your Space will be live at:**344`https://huggingface.co/spaces/YOUR_USERNAME/music-metadata-engine`345 346Good luck! 🚀347