DEPLOYMENT.md

# 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