Hadith Semantic Search - Deployment Guide

Architecture

This application consists of:

• API: Express.js server with ChromaDB vector search
• Client: React + Vite frontend with Arabic/English hadith search
• ChromaDB: Vector database for semantic embeddings

Local Development (Docker Compose)

# Start all services
docker-compose up --build

# Access:
# - Client: http://localhost:80
# - API: http://localhost:3000
# - ChromaDB: http://localhost:8000

Deploy to Render

Option 1: Blueprint (Recommended)

1. Push code to GitHub
2. Connect your repo to Render via the render.yaml blueprint
3. Set environment variables in Render dashboard:
   • COHERE_API_KEY (required)
   • VITE_GEMINI_KEY (for client translation)

Option 2: Manual Services

1. API Service:

   • Create Web Service
   • Build: npm install
   • Start: node src/index.js
   • Env: COHERE_API_KEY, CHROMA_URL (if using Chroma Cloud)

2. ChromaDB:

   • Create Web Service with Docker
   • Use Dockerfile.chroma
   • Or use Chroma Cloud and set CHROMA_URL

3. Client:

   • Create Static Site
   • Root directory: client
   • Build: npm install && npm run build
   • Publish: dist
   • Env: VITE_API_URL=https://your-api.onrender.com/api

Environment Variables

API (.env)

COHERE_API_KEY=your_key_here
CHROMA_HOST=chroma  # for docker, or use CHROMA_URL for cloud
CHROMA_PORT=8000

Client (client/.env)

VITE_GEMINI_KEY=your_key_here  # For Arabic translation
VITE_API_URL=/api  # or full URL for separate deployment

File Structure

├── src/                  # API source
├── client/              # React frontend
│   ├── src/
│   ├── Dockerfile
│   └── nginx.conf
├── data/                # Hadith dataset
├── docker-compose.yml   # Local development
├── Dockerfile           # API Dockerfile
├── Dockerfile.chroma    # ChromaDB Dockerfile
├── Dockerfile.render    # Combined production build
├── render.yaml          # Render deployment blueprint
└── render-nginx.conf    # Nginx config for combined deployment