🚀 Quick Start Guide¶

Get RAG Modulo up and running in minutes with this comprehensive quick start guide.

Prerequisites¶

Before you begin, ensure you have the following installed:

• Docker & Docker Compose V2 - Install Docker Desktop
• Python 3.12+ (for local development)
• Node.js 18+ (for frontend development)
• Git - Install Git

🐳 Option 1: Docker (Recommended)¶

The fastest way to get started is using our pre-built Docker images.

Step 1: Clone the Repository¶

git clone https://github.com/manavgup/rag-modulo.git
cd rag-modulo

Step 2: Set Up Environment¶

# Copy the example environment file
cp env.example .env

# Edit .env with your API keys
nano .env  # or use your preferred editor

Step 3: Start the Application¶

# Start with pre-built images (recommended)
make run-ghcr

That's it! 🎉 The application should now be running.

Step 4: Verify Installation¶

Check that all services are running:

# Check container status
docker compose ps

# View logs
make logs

Access Points¶

🛠️ Option 2: Local Development¶

For developers who want to build and run locally.

Step 1: Initialize Development Environment¶

# Initialize development environment
make dev-init

# This creates:
# - .env.dev (development configuration)
# - .env (production configuration)

Step 2: Build Local Images¶

# Build all development images
make dev-build

# This builds:
# - Backend development image
# - Frontend development image
# - Test image

Step 3: Start Development Environment¶

# Start development environment
make dev-up

# Validate everything is working
make dev-validate

Step 4: Development Commands¶

# Restart with latest changes
make dev-restart

# View logs
make dev-logs

# Check status
make dev-status

# Stop environment
make dev-down

☁️ Option 3: GitHub Codespaces¶

Perfect for cloud development without local setup.

Step 1: Create Codespace¶

1. Go to the repository: https://github.com/manavgup/rag_modulo
2. Click "Code" → "Codespaces"
3. Click "Create codespace" on your branch
4. Wait for environment to load (2-3 minutes)

Step 2: Start Coding¶

The environment is automatically configured with: - All dependencies installed - Development environment ready - Ports forwarded for testing

Step 3: Access Services¶

Services are automatically available at: - Frontend: https://your-codespace-url-3000.preview.app.github.dev - Backend: https://your-codespace-url-8000.preview.app.github.dev

🔧 Configuration¶

Required Environment Variables¶

Edit your .env file with the following required variables:

# Database Configuration
VECTOR_DB=milvus
MILVUS_HOST=localhost
MILVUS_PORT=19530
DB_HOST=localhost
DB_PORT=5432

# LLM Provider Settings (choose one or more)
WATSONX_INSTANCE_ID=your-instance-id
WATSONX_APIKEY=your-api-key
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# Application Settings
EMBEDDING_MODEL=all-minilm-l6-v2
DATA_DIR=/app/data

Optional Configuration¶

# Authentication (for production)
IBM_CLIENT_ID=your-client-id
IBM_CLIENT_SECRET=your-client-secret

# Development Mode
DEVELOPMENT_MODE=true
SKIP_AUTH=true
TESTING=true

🧪 Verify Installation¶

Health Checks¶

# Check all services are healthy
make dev-validate

# Test backend API
curl http://localhost:8000/health

# Test frontend
curl http://localhost:3000

Run Tests¶

# Run quick tests
make test-atomic

# Run comprehensive tests
make test-all

🎯 First Steps¶

1. Create Your First Collection¶

# Using CLI
rag-cli collections create --name "my-first-collection"

# Or using the web interface at http://localhost:3000

2. Upload Documents¶

# Upload a document
rag-cli documents upload --collection-id <collection-id> --file document.pdf

# Or use the web interface

3. Ask Your First Question¶

# Ask a question
rag-cli search query --collection-id <collection-id> --query "What is this document about?"

# Or use the web interface

🔍 Troubleshooting¶

Common Issues¶

# Check Docker is running
docker --version

# Check service logs
make logs

# Restart services
make stop-containers
make run-services

# Run tests in Docker
make test testfile=tests/unit/test_example.py

# Or use development environment
make dev-test

Getting Help¶

1. 📚 Documentation: Check our comprehensive docs
2. 🐛 Issues: Report bugs
3. 💬 Discussions: Ask questions
4. 🔧 Troubleshooting: Common issues

🎉 Next Steps¶

Now that you have RAG Modulo running, explore these resources:

• 📚 Full Documentation - Comprehensive guides
• 🛠️ Development Guide - Development best practices
• 🧪 Testing Guide - Testing strategies
• 🚀 Deployment Guide - Production deployment
• 🖥️ CLI Guide - Command-line interface

💡 Tips¶

• Use Docker: It's the easiest way to get started
• Check Logs: Use make logs to debug issues
• Validate Setup: Run make dev-validate to check everything
• Start Small: Begin with simple documents and queries
• Read Documentation: Our docs are comprehensive and helpful