Spaces:
Sleeping
Sleeping
| # Hugging Face Deployment Guide | |
| Complete step-by-step guide to deploy your RAG chatbot to Hugging Face Spaces via GitHub Actions CI/CD. | |
| --- | |
| ## 📋 Prerequisites | |
| - GitHub account with repository: https://github.com/Abeshith/RAG | |
| - Hugging Face account (free): https://huggingface.co | |
| - All API keys ready (Groq, MongoDB, Redis, Qdrant) | |
| --- | |
| ## 🚀 Deployment Steps | |
| ### **Step 1: Create Hugging Face Space** | |
| 1. Go to: https://huggingface.co/new-space | |
| 2. Fill in details: | |
| ``` | |
| Owner: [Your HF username] | |
| Space name: rag-chatbot (or your choice) | |
| License: MIT | |
| Select SDK: Docker | |
| Hardware: CPU basic (free) or upgrade to GPU | |
| ``` | |
| 3. Click **"Create Space"** | |
| 4. **Important:** Copy your Space URL | |
| ``` | |
| Example: https://huggingface.co/spaces/YourUsername/rag-chatbot | |
| ``` | |
| 5. Note down: | |
| - **HF_USERNAME**: Your Hugging Face username | |
| - **HF_SPACE_NAME**: The space name (e.g., `rag-chatbot`) | |
| --- | |
| ### **Step 2: Get Hugging Face Access Token** | |
| 1. Go to: https://huggingface.co/settings/tokens | |
| 2. Click **"New token"** | |
| 3. Fill in: | |
| ``` | |
| Name: github-actions-deploy | |
| Role: Write | |
| ``` | |
| 4. Click **"Generate token"** | |
| 5. **Copy the token** (starts with `hf_...`) | |
| ⚠️ Save it immediately - you won't see it again! | |
| --- | |
| ### **Step 3: Add GitHub Secrets** | |
| 1. Go to: https://github.com/Abeshith/RAG/settings/secrets/actions | |
| 2. Click **"New repository secret"** and add these **3 secrets**: | |
| **Secret 1:** | |
| ``` | |
| Name: HF_TOKEN | |
| Value: [Paste your HF token from Step 2] | |
| ``` | |
| **Secret 2:** | |
| ``` | |
| Name: HF_USERNAME | |
| Value: [Your Hugging Face username] | |
| ``` | |
| **Secret 3:** | |
| ``` | |
| Name: HF_SPACE_NAME | |
| Value: rag-chatbot (or whatever you named it) | |
| ``` | |
| 3. Verify all 3 secrets are added | |
| --- | |
| ### **Step 4: Add Hugging Face Space Secrets** | |
| Your app needs API keys to run. Add them to HF Space: | |
| 1. Go to your Space: `https://huggingface.co/spaces/[username]/[space-name]` | |
| 2. Click **"Settings"** tab | |
| 3. Scroll to **"Repository secrets"** | |
| 4. Add these **5 secrets**: | |
| ``` | |
| Secret 1: | |
| Name: GROQ_API_KEY | |
| Value: [Your Groq API key] | |
| Secret 2: | |
| Name: MONGODB_URI | |
| Value: [Your MongoDB connection string] | |
| Secret 3: | |
| Name: REDIS_URL | |
| Value: [Your Redis connection URL] | |
| Secret 4: | |
| Name: QDRANT_URL | |
| Value: [Your Qdrant cluster URL] | |
| Secret 5: | |
| Name: QDRANT_API_KEY | |
| Value: [Your Qdrant API key] | |
| ``` | |
| 5. Click **"Save"** for each secret | |
| --- | |
| ### **Step 5: Trigger Deployment** | |
| Now everything is configured! Deploy your app: | |
| **Option A: Automatic (Push to GitHub)** | |
| ```bash | |
| # Make any small change (or just trigger workflow) | |
| git commit --allow-empty -m "Trigger HF deployment" | |
| git push origin main | |
| ``` | |
| **Option B: Manual (GitHub UI)** | |
| 1. Go to: https://github.com/Abeshith/RAG/actions | |
| 2. Click **"Deploy to Hugging Face Spaces"** workflow | |
| 3. Click **"Run workflow"** → **"Run workflow"** | |
| --- | |
| ### **Step 6: Monitor Deployment** | |
| 1. **Watch GitHub Actions:** | |
| - Go to: https://github.com/Abeshith/RAG/actions | |
| - Click the running workflow | |
| - Monitor progress through 3 stages: | |
| - ✅ Stage 1: Test Application (~2-3 min) | |
| - ✅ Stage 2: Build Docker Image (~3-5 min) | |
| - ✅ Stage 3: Deploy to HF Spaces (~1 min) | |
| 2. **Watch Hugging Face Build:** | |
| - Go to your Space: `https://huggingface.co/spaces/[username]/[space-name]` | |
| - Click **"Build"** tab | |
| - Watch Docker image build (~5-10 min) | |
| - Status will change: Building → Running | |
| 3. **Check Application:** | |
| - Once status is "Running", click **"App"** tab | |
| - Your chatbot should load! | |
| - Try uploading a document and chatting | |
| --- | |
| ## 🔍 Troubleshooting | |
| ### Issue 1: GitHub Actions Fails at "Deploy to HF Spaces" | |
| **Solution:** Check if all 3 GitHub secrets are set correctly: | |
| - Go to: https://github.com/Abeshith/RAG/settings/secrets/actions | |
| - Verify: `HF_TOKEN`, `HF_USERNAME`, `HF_SPACE_NAME` | |
| ### Issue 2: HF Space Shows "Application Error" | |
| **Solution:** Check if all 5 HF Space secrets are set: | |
| - Go to Space → Settings → Repository secrets | |
| - Verify all API keys are present | |
| ### Issue 3: App Starts but Database Connection Fails | |
| **Solution:** Verify your connection strings: | |
| - MongoDB URI should start with `mongodb+srv://` or `mongodb://` | |
| - Redis URL should start with `redis://` or `rediss://` | |
| - Qdrant URL should be the full cluster URL | |
| ### Issue 4: Docker Build Fails | |
| **Solution:** Check HF build logs: | |
| - Go to Space → Build tab → View logs | |
| - Common issues: Missing dependencies, syntax errors | |
| --- | |
| ## 📊 CI/CD Pipeline Stages | |
| ### Stage 1: Test Application (2-3 min) | |
| - ✅ Checkout code | |
| - ✅ Install Python 3.11 | |
| - ✅ Cache dependencies | |
| - ✅ Install requirements | |
| - ✅ Run pytest with coverage | |
| - ✅ Upload test results | |
| **Fails if:** Tests don't pass | |
| ### Stage 2: Build Docker Image (3-5 min) | |
| - ✅ Setup Docker Buildx | |
| - ✅ Build image from Dockerfile | |
| - ✅ Test container startup | |
| - ✅ Verify health check | |
| **Fails if:** Docker build errors or container won't start | |
| ### Stage 3: Deploy to HF Spaces (1 min) | |
| - ✅ Configure git | |
| - ✅ Verify secrets | |
| - ✅ Push to HF git repository | |
| - ✅ Trigger HF rebuild | |
| **Fails if:** Secrets missing or HF authentication fails | |
| --- | |
| ## 🎯 What Happens After Deployment? | |
| 1. **Hugging Face receives your code** | |
| 2. **Detects Dockerfile** → Starts Docker build | |
| 3. **Builds image** with all dependencies (~5-10 min) | |
| 4. **Starts container** on port 7860 | |
| 5. **Runs health check** every 30 seconds | |
| 6. **App is live!** At `https://huggingface.co/spaces/[username]/[space-name]` | |
| --- | |
| ## 🔄 Future Deployments | |
| Every time you push to `main` branch: | |
| 1. GitHub Actions runs automatically | |
| 2. Tests → Build → Deploy pipeline executes | |
| 3. HF Space automatically rebuilds | |
| 4. New version goes live (~10-15 min total) | |
| --- | |
| ## 📝 Quick Reference | |
| **Your GitHub Repo:** | |
| https://github.com/Abeshith/RAG | |
| **GitHub Actions:** | |
| https://github.com/Abeshith/RAG/actions | |
| **GitHub Secrets:** | |
| https://github.com/Abeshith/RAG/settings/secrets/actions | |
| **Your HF Space:** | |
| https://huggingface.co/spaces/[YOUR_USERNAME]/[YOUR_SPACE_NAME] | |
| **HF Space Settings:** | |
| https://huggingface.co/spaces/[YOUR_USERNAME]/[YOUR_SPACE_NAME]/settings | |
| --- | |
| ## ✅ Checklist | |
| Before deployment, ensure: | |
| - [ ] HF Space created | |
| - [ ] HF token generated | |
| - [ ] 3 GitHub secrets added (HF_TOKEN, HF_USERNAME, HF_SPACE_NAME) | |
| - [ ] 5 HF Space secrets added (all API keys) | |
| - [ ] Code pushed to main branch | |
| - [ ] GitHub Actions workflow triggered | |
| - [ ] HF build completed successfully | |
| - [ ] App is accessible and working | |
| --- | |
| ## 🎉 Success! | |
| Once all stages pass and HF shows "Running": | |
| 1. Visit your Space URL | |
| 2. Upload a document (PDF/TXT/MD) | |
| 3. Ask questions about it | |
| 4. Toggle RAG ON/OFF to compare responses | |
| 5. Share your Space with others! | |
| --- | |
| **Need Help?** | |
| - GitHub Actions Logs: https://github.com/Abeshith/RAG/actions | |
| - HF Build Logs: Your Space → Build tab | |
| - HF Community: https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat/discussions | |