Merge branch 'main' into make-commands

DEVELOPMENT.md

@@ -0,0 +1,169 @@
+# OpenRAG Development Guide
+
+Quick start commands using the Makefile for development and production workflows.
+
+## 🚀 Quick Start
+
+### First Time Setup
+```bash
+# Install all dependencies (backend + frontend)
+make install
+
+# Or install individually
+make install-frontend  # Frontend only
+uv sync                 # Backend only
+```
+
+### Development Mode
+```bash
+# Start both backend and frontend (recommended)
+make dev
+
+# Or run services individually
+make backend    # Backend only (http://localhost:8000)
+make frontend   # Frontend only (http://localhost:3000)
+
+# Alternative: Run both in parallel
+make dev-all
+```
+
+## 🛠️ Available Commands
+
+### Development
+| Command | Description |
+|---------|-------------|
+| `make dev` | Start both backend and frontend servers |
+| `make dev-all` | Start both services in parallel |
+| `make backend` | Run backend server only |
+| `make frontend` | Run frontend development server only |
+
+### Production
+| Command | Description |
+|---------|-------------|
+| `make run` | Run backend in production mode |
+| `make build` | Build frontend for production |
+
+### Installation
+| Command | Description |
+|---------|-------------|
+| `make install` | Install all dependencies |
+| `make install-frontend` | Install frontend dependencies only |
+
+### Docker
+| Command | Description |
+|---------|-------------|
+| `make docker-build` | Build Docker images |
+| `make docker-up` | Start services with docker-compose |
+| `make docker-up-cpu` | Start services (CPU mode) |
+| `make docker-down` | Stop docker-compose services |
+| `make docker-down-cpu` | Stop services (CPU mode) |
+
+### Utilities
+| Command | Description |
+|---------|-------------|
+| `make help` | Show all available commands |
+| `make check` | Test backend health endpoint |
+| `make lint` | Run linting checks |
+| `make test` | Run tests |
+| `make clean` | Clean build artifacts |
+
+## 🌐 Service URLs
+
+- **Backend API**: http://localhost:8000
+- **Frontend**: http://localhost:3000
+- **Health Check**: http://localhost:8000/.well-known/openid-configuration
+
+## 📋 Environment Setup
+
+### Backend Environment Variables
+Create a `.env` file in the project root with:
+
+```env
+OPENSEARCH_HOST=localhost
+OPENSEARCH_PORT=9200
+OPENSEARCH_USERNAME=admin
+OPENSEARCH_PASSWORD=your_password
+LANGFLOW_URL=http://localhost:7860
+OPENAI_API_KEY=your_openai_key
+```
+
+### Manual Backend Run (Alternative)
+```bash
+# With inline environment variables
+OPENSEARCH_HOST=localhost OPENSEARCH_PORT=9200 OPENSEARCH_USERNAME=admin OPENSEARCH_PASSWORD=... \
+LANGFLOW_URL=http://localhost:7860 OPENAI_API_KEY=... \
+uv run python src/main.py
+
+# Using .env file (recommended)
+uv run python src/main.py
+```
+
+## 🔧 Development Workflow
+
+1. **Start Development**:
+   ```bash
+   make dev
+   ```
+
+2. **Check Services**:
+   ```bash
+   make check
+   ```
+
+3. **Run Tests & Linting**:
+   ```bash
+   make lint
+   make test
+   ```
+
+4. **Build for Production**:
+   ```bash
+   make build
+   ```
+
+## 🐳 Docker Development
+
+For containerized development:
+
+```bash
+# GPU mode (default)
+make docker-up
+
+# CPU mode
+make docker-up-cpu
+
+# Stop services
+make docker-down        # GPU mode
+make docker-down-cpu    # CPU mode
+```
+
+## 🆘 Troubleshooting
+
+### Common Issues
+
+**Backend not starting?**
+- Check your `.env` file exists and has required variables
+- Verify dependencies: `uv sync`
+- Test manually: `uv run python src/main.py`
+
+**Frontend not starting?**
+- Install dependencies: `make install-frontend`
+- Check Node.js version compatibility
+
+**Import errors?**
+- The Makefile sets `PYTHONPATH=src` automatically
+- For manual runs: `PYTHONPATH=src uv run python src/main.py`
+
+**Health check failing?**
+```bash
+make check
+# or
+curl http://localhost:8000/.well-known/openid-configuration
+```
+
+## 📚 Additional Resources
+
+- Backend code: `src/`
+- Frontend code: `frontend/`
+- Docker configs: `docker-compose.yml`, `docker-compose-cpu.yml`
+- Environment example: `.env.example`

Makefile

@@ -0,0 +1,132 @@
+# OpenRAG Makefile
+# Standard commands for running OpenRAG in production and development modes
+
+.PHONY: help install install-frontend run backend frontend dev dev-all clean lint test build docker-build docker-up docker-down
+
+# Default target
+help:
+	@echo "OpenRAG - Available commands:"
+	@echo ""
+	@echo "Installation:"
+	@echo "  install           Install all dependencies (backend + frontend)"
+	@echo "  install-frontend  Install frontend dependencies only"
+	@echo ""
+	@echo "Development:"
+	@echo "  dev              Run both backend and frontend in development mode"
+	@echo "  backend          Run backend server only"
+	@echo "  frontend         Run frontend development server only"
+	@echo ""
+	@echo "Production:"
+	@echo "  run              Run backend in production mode"
+	@echo "  build            Build frontend for production"
+	@echo ""
+	@echo "Docker:"
+	@echo "  docker-build     Build Docker images"
+	@echo "  docker-up        Start services with docker-compose"
+	@echo "  docker-up-cpu    Start services with docker-compose (CPU mode)"
+	@echo "  docker-down      Stop docker-compose services"
+	@echo "  docker-down-cpu  Stop docker-compose services (CPU mode)"
+	@echo ""
+	@echo "Utilities:"
+	@echo "  lint             Run linting checks"
+	@echo "  clean            Clean build artifacts and dependencies"
+	@echo "  test             Run tests (if available)"
+	@echo ""
+	@echo "Quick check:"
+	@echo "  check            Test backend health endpoint"
+
+# Installation
+install: install-frontend
+	@echo "Installing backend dependencies..."
+	uv sync
+
+install-frontend:
+	@echo "Installing frontend dependencies..."
+	cd frontend && npm install
+
+# Backend commands
+backend:
+	@echo "Starting backend server..."
+	PYTHONPATH=src uv run python src/main.py
+
+run: backend
+
+# Frontend commands  
+frontend:
+	@echo "Starting frontend development server..."
+	cd frontend && npm run dev
+
+build:
+	@echo "Building frontend for production..."
+	cd frontend && npm run build
+
+# Development mode
+dev:
+	@echo "Starting development mode..."
+	@echo "This will start both backend and frontend servers."
+	@echo "Backend: http://localhost:8000"
+	@echo "Frontend: http://localhost:3000"
+	@echo ""
+	@echo "Starting backend in background..."
+	@PYTHONPATH=src uv run python src/main.py &
+	@sleep 3
+	@echo "Starting frontend..."
+	@cd frontend && npm run dev
+
+# Alternative dev command that runs both services in parallel
+dev-all:
+	@echo "Starting both backend and frontend in parallel..."
+	@echo "Use Ctrl+C to stop both services"
+	@(PYTHONPATH=src uv run python src/main.py &) && (cd frontend && npm run dev)
+
+# Utilities
+lint:
+	@echo "Running backend linting..."
+	@if command -v ruff > /dev/null 2>&1; then \
+		ruff check .; \
+	else \
+		echo "Ruff not found, skipping backend linting"; \
+	fi
+	@echo "Running frontend linting..."
+	@cd frontend && npm run lint
+
+test:
+	@echo "Running tests..."
+	@if [ -f "pytest.ini" ] || [ -f "pyproject.toml" ]; then \
+		uv run pytest; \
+	else \
+		echo "No test configuration found"; \
+	fi
+
+check:
+	@echo "Checking backend health..."
+	@curl -s http://localhost:8000/.well-known/openid-configuration > /dev/null && echo "✓ Backend is running" || echo "✗ Backend not responding"
+
+clean:
+	@echo "Cleaning build artifacts..."
+	rm -rf frontend/.next
+	rm -rf frontend/node_modules
+	rm -rf .venv
+	rm -rf src/__pycache__
+	rm -rf **/__pycache__
+
+# Docker commands
+docker-build:
+	@echo "Building Docker images..."
+	docker-compose build
+
+docker-up:
+	@echo "Starting services with docker-compose..."
+	docker-compose up -d
+
+docker-up-cpu:
+	@echo "Starting services with docker-compose (CPU mode)..."
+	docker-compose -f docker-compose-cpu.yml up -d
+
+docker-down:
+	@echo "Stopping docker-compose services..."
+	docker-compose down
+
+docker-down-cpu:
+	@echo "Stopping docker-compose services (CPU mode)..."
+	docker-compose -f docker-compose-cpu.yml down