Quick Start - SageAI

Prerequisites

Docker & Docker Compose installed
Ollama installed locally (we'll show you how)
At least 8GB RAM (16GB recommended)

Install Ollama

Ollama runs your AI models locally. Choose your operating system:

Run this single command in your terminal:

curl -fsSL https://ollama.com/install.sh | sh

Note: On most Linux distributions, Ollama will automatically start as a service.

Option 1: Using Homebrew (recommended)

brew install ollama

Option 2: Download the installer

Download for macOS

Tip: After installation, start Ollama from Applications or run ollama serve

Download and run the Windows installer:

Download for Windows

Note: Ollama will run in the system tray after installation. It starts automatically on boot.

Pull the LLM Model

Download the Llama 3 model (recommended for best results):

ollama pull llama3:latest

Model Options

llama3:latest - Full model ~4.7GB

llama3.2:1b - Smaller, faster ~1.3GB

llama3.2:3b - Balanced ~2GB

💡 For slower machines, try the smaller models. For best quality, use llama3:latest.

This will take a few minutes depending on your internet speed. Go grab a coffee! ☕

Download Docker Compose File

Choose the configuration that matches your setup:

Development Mode

DEV

For local development with hot-reload and debugging enabled.(Note: the source code needed to be cloned to run dev compose files)

Linux Dev

Mac/Win Dev

Production Mode

PROD

Optimized builds for production deployment.

Linux Prod

Mac/Win Prod

Which one should I choose?

Linux: Uses host networking for better Ollama integration
Mac/Windows: Uses Docker bridge networking with host.docker.internal
Dev: Includes hot-reload, debug mode, and verbose logging
Prod: Optimized builds, minified assets, production-ready

💡 Recommendation: Start with the Dev version for your OS. It's easier to debug!

Clone the Repository

For Dev mode, you need to clone the repository to build the services locally. For Prod mode, you can skip to Step 5 and just download the compose file.

Dev vs Prod Mode

Dev Mode: Builds services from source (requires git clone)
Prod Mode: Uses pre-built Docker images (no git clone needed)

# Clone the repository
git clone --branch submission/ridowan https://github.com/WhisperNet/research-paper-rag-assessment.git

# Navigate to the project directory
cd research-paper-rag-assessment
# For Linux Dev(Run this from the project root)
docker compose -f infra/docker-compose.linux.dev.yml up --build
# For Mac/Windows Dev(Run this from the project root)
docker compose -f infra/docker-compose.mac-win.dev.yml up --build

💡 Note: This step is only required if you're using Dev compose files. Production files use pre-built images and don't need the source code.

Launch SageAI

Navigate to the resources folder and run the compose file:

# Navigate to resources folder
cd resources

# For Linux Dev (Run this from the project root)
docker compose -f infra/docker-compose.linux.dev.yml up --build

# Or for Mac/Windows Dev (Run this from the project root)
docker compose -f infra/docker-compose.mac-win.dev.yml up --build

# Or for Production (any OS)
docker compose -f docker-compose.linux.prod.yml up -d
docker compose -f docker-compose.mac-win.prod.yml up -d

What happens next?

✓ Docker pulls necessary images (MongoDB, Qdrant, Redis)
✓ Builds the backend API and embedder service
✓ Builds the React frontend
✓ Connects all services together
✓ Verifies Ollama is running on your host

⏱️ First build takes 3-5 minutes. Subsequent starts are under 30 seconds!

🎉 You're Ready!

Open your browser and navigate to:

http://localhost:8080

Frontend

Port 8080

Backend API

Port 8000

Embedder Service

Port 9100

Troubleshooting

Ollama connection error

Make sure Ollama is running: ollama serve
Check if it's accessible: curl http://localhost:11434

Port already in use

Stop conflicting services or modify the ports in the compose file.
Check what's using a port: lsof -i :8080 (Mac/Linux)

Docker build fails

Ensure you have enough disk space (at least 10GB free).
Try: docker system prune to clean up old images.

Get Started in 30 Seconds