dataTeam24/GeneralPurposeRAG

1# Hugging Face Spaces Docker Deployment2 3This document describes the deployment refactor for running the RAG application on **Hugging Face Spaces** with Docker. Only infrastructure, configuration, and deployment concerns were changed; **RAG logic and retrieval internals were not modified**.4 5---6 7## Folder structure (recommended)8 9```10General-Purpose-RAG-Application-TELA/11├── backend/                 # FastAPI app and RAG logic12│   ├── api.py               # REST API + optional static serve + CORS13│   ├── config.py           # Env-based config (no secrets in repo)14│   ├── run_server.py        # Uvicorn entry (0.0.0.0, PORT)15│   ├── requirements.txt     # Python deps (production)16│   └── ...17├── frontend/                # React (Vite) app18│   ├── src/19│   ├── build/              # Output of `npm run build` (used by Docker)20│   ├── package.json21│   └── vite.config.ts       # base: '/', build.outDir: 'build'22├── static/                  # Only in container: copy of frontend/build23├── Dockerfile               # Multi-stage: build frontend → run backend + static24├── .dockerignore25└── DEPLOYMENT.md            # This file26```27 28At **runtime in the container**:29- Working directory for the app is `/app/backend`.30- Project root is `/app` (chroma_db, rag_sessions.db, bm25_indices, etc. are created here).31- Static frontend is at `/app/static` (set via `STATIC_DIR`).32 33---34 35## Required code modifications (summary)36 37### 1. Environment configuration (`backend/config.py`)38- **Before:** Hardcoded values and API keys (e.g. `GROQ_API_KEY = "gsk_..."`).39- **After:** All values loaded via `os.getenv()` with sensible defaults only for non-sensitive settings. API keys have no default (empty string); set in environment for production.40- **Why:** Secrets must not be committed; Hugging Face Spaces use env vars for keys.41 42### 2. Backend server43- **New:** `backend/run_server.py` runs uvicorn with `host="0.0.0.0"` and `port=int(os.getenv("PORT", "7860"))`.44- **Why:** HF Spaces require binding to `0.0.0.0` and use port **7860** by default.45 46### 3. CORS (`backend/api.py`)47- **Before:** `allow_origins=["http://localhost:5173", "http://localhost:3000"]`.48- **After:** Origins from `CORS_ORIGINS` env (default `"*"`). For local dev with a separate Vite server, set e.g. `CORS_ORIGINS=http://localhost:5173,http://localhost:3000`.49- **Why:** In Docker the frontend is same-origin; `*` works. Local dev can override.50 51### 4. React build and static serve52- **Frontend:** `frontend/vite.config.ts` — `base: '/'`, `build.outDir: 'build'`.53- **Backend:** When `STATIC_DIR` is set and the directory exists, FastAPI mounts `/assets` for the built assets and adds a catch-all route that serves existing static files under that dir or `index.html` (SPA fallback).54- **Why:** Single container serves both API and React app; client-side routing works.55 56### 5. Docker57- **Dockerfile:** Multi-stage: Stage 1 builds the React app; Stage 2 installs Python deps, copies backend and `frontend/build` → `/app/static`, sets `STATIC_DIR=/app/static`, exposes 7860, runs `python run_server.py` from `/app/backend`.58- **.dockerignore:** Excludes `node_modules`, `.git`, local vector DB dirs (`chroma_db/`, `vector_store/`, etc.), `__pycache__`, `venv`, logs, and dev-only files.59 60### 6. requirements.txt61- Removed dev-only packages: `streamlit`, `altair`, `pydeck`, `kubernetes`, `langsmith`, `GitPython`, `hf-xet`, `watchdog`, `build`, `typer`, `typer-slim`, `shellingham`, `mypy_extensions`, `pyreadline3`, `toml` (if unused). Kept all dependencies required for FastAPI, ChromaDB, embeddings, and document processing.62 63### 7. Startup and paths64- No changes to RAG or retrieval code. All paths in backend already use `os.path.dirname(os.path.abspath(__file__))` and relative segments (e.g. `".."` for project root), so they work in the container with `/app` as project root. Vector DB and SQLite initialize on first use; no Windows or absolute path assumptions.65 66---67 68## Environment variables (production)69 70Set these in Hugging Face Spaces (or your deployment platform); do **not** commit secrets.71 72| Variable | Description | Default |73|----------|-------------|---------|74| `PORT` | HTTP port | `7860` |75| `GROQ_API_KEY` | Groq API key (required if using Groq) | — |76| `LLM_PROVIDER` | `groq` or `ollama` | `groq` |77| `GROQ_MODEL` | Groq model name | `llama-3.3-70b-versatile` |78| `OLLAMA_MODEL` | Ollama model (if provider is ollama) | `phi3:mini` |79| `STATIC_DIR` | Path to React build in container | `/app/static` (set in Dockerfile) |80| `CORS_ORIGINS` | Comma-separated origins or `*` | `*` |81| `TOP_K`, `CHUNK_SIZE`, etc. | Optional tuning; see `config.py` | Sensible defaults |82 83---84 85## Build and run locally (Docker)86 87```bash88docker build -t rag-app .89docker run -p 7860:7860 -e GROQ_API_KEY=your_key rag-app90```91 92Then open `http://localhost:7860`.93 94---95 96## Troubleshooting97 98### "Unexpected token '<', \"<!doctype \"... is not valid JSON"99 100This usually means the browser **cached an old HTML response** for an API URL (e.g. when the SPA fallback previously returned `index.html` for `/sessions`). The Network tab will show **"(from disk cache)"** and **Content-Type: text/html** for that request.101 102**Fix:**103 1041. **Clear the cache for this origin** so the next request hits the server:105   - **Chrome/Edge:** DevTools → Application → Storage → "Clear site data" for `http://localhost:7860`, or close the tab and clear browsing data for the last hour.106   - **Firefox:** DevTools → Storage → "Clear All" for the site, or Settings → Privacy → Clear Data (cookies and cache).107   - **Quick dev option:** DevTools → Network tab → check **"Disable cache"**, then reload. Requests will bypass cache while DevTools is open.108 1092. **Hard reload** after clearing: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac).110 1113. Ensure the app is built and running with the latest backend (so API responses send `Cache-Control: no-store`) and frontend (so `fetch` uses `cache: 'no-store'`). After that, the browser will not cache API responses and the error will not recur.112 113---114 115## What was not changed116 117- RAG retrieval logic, chunking, or indexing.118- API endpoint paths or request/response shapes.119- Frontend API usage (still relative URLs with `API_BASE = ''`).120- Core backend modules (retriever, indexer, llm, prompt, upload_handler, etc.) except where they already read from `config` (which now uses env).121