Improved CI/CD pipeline with 3-stage

.github/workflows/deploy.yml

@@ -7,34 +7,124 @@ on:
   workflow_dispatch:
 
 jobs:
-  deploy:
+  # Stage 1: Run Tests
+  test:
+    name: Test Application
     runs-on: ubuntu-latest
     
     steps:
-      - name: Checkout repository
+      - name: Checkout code
         uses: actions/checkout@v4
       
-      - name: Set up Python
+      - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
           python-version: '3.11'
       
+      - name: Cache Python dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
+          pip install pytest pytest-asyncio httpx pytest-cov
+      
+      - name: Run unit tests
+        run: |
+          pytest tests/ -v --tb=short --cov=app --cov-report=term-missing
+      
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: test-results
+          path: |
+            .coverage
+            htmlcov/
+  
+  # Stage 2: Build Docker Image
+  build:
+    name: Build Docker Image
+    runs-on: ubuntu-latest
+    needs: test
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Build Docker image
+        run: |
+          docker build -t rag-chatbot:latest .
       
-      - name: Run tests
+      - name: Test Docker image
         run: |
-          pip install pytest pytest-asyncio httpx
-          pytest tests/ -v --tb=short || true
+          docker run -d --name test-container -p 7860:7860 \
+            -e GROQ_API_KEY=test \
+            -e MONGODB_URI=test \
+            -e REDIS_URL=test \
+            -e QDRANT_URL=test \
+            -e QDRANT_API_KEY=test \
+            rag-chatbot:latest
+          sleep 10
+          docker logs test-container
+          docker stop test-container
+          docker rm test-container
+  
+  # Stage 3: Deploy to Hugging Face Spaces
+  deploy:
+    name: Deploy to HF Spaces
+    runs-on: ubuntu-latest
+    needs: [test, build]
+    if: github.ref == 'refs/heads/main'
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Configure Git
+        run: |
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "GitHub Actions Bot"
       
-      - name: Push to Hugging Face Spaces
+      - name: Deploy to Hugging Face
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_USERNAME: ${{ secrets.HF_USERNAME }}
+          HF_SPACE_NAME: ${{ secrets.HF_SPACE_NAME }}
         run: |
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          git config --global user.name "github-actions[bot]"
+          if [ -z "$HF_TOKEN" ]; then
+            echo "Error: HF_TOKEN secret not set"
+            exit 1
+          fi
+          if [ -z "$HF_USERNAME" ]; then
+            echo "Error: HF_USERNAME secret not set"
+            exit 1
+          fi
+          if [ -z "$HF_SPACE_NAME" ]; then
+            echo "Error: HF_SPACE_NAME secret not set"
+            exit 1
+          fi
+          
+          echo "Deploying to Hugging Face Space: $HF_USERNAME/$HF_SPACE_NAME"
           
-          git remote add hf https://HF_USERNAME:$HF_TOKEN@huggingface.co/spaces/HF_USERNAME/rag-chatbot
+          git remote add hf https://$HF_USERNAME:$HF_TOKEN@huggingface.co/spaces/$HF_USERNAME/$HF_SPACE_NAME
           git push hf main --force
+          
+          echo "✅ Successfully deployed to https://huggingface.co/spaces/$HF_USERNAME/$HF_SPACE_NAME"
+      
+      - name: Deployment notification
+        if: success()
+        run: |
+          echo "🚀 Deployment successful!"
+          echo "🔗 View your Space at: https://huggingface.co/spaces/${{ secrets.HF_USERNAME }}/${{ secrets.HF_SPACE_NAME }}"

DEPLOYMENT.md

@@ -0,0 +1,293 @@
+# 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