solr-rag-lab — Local Dev Runbook

Minimal-yet-realistic RAG lab on Kotlin + Spring Boot 3 (WebFlux) with Solr 9.6 (BM25 + HNSW vectors) and native Ollama.

---

1) Prerequisites

• macOS with Docker Desktop
• JDK 21 (Temurin recommended) — used in container build; local build uses Gradle wrapper
• Ollama (native) running on host: http://localhost:11434
• Docker Compose v2
• (Optional) External Solr: http://localhost:8983

Pull models (first run)

# Generation model(s)
ollama pull llama3

# Embeddings model
ollama pull nomic-embed-text

---

2) Project Structure

solr-rag-lab/
├─ infra/
│  ├─ docker-compose.yml              # base: search-service only
│  └─ docker-compose.solr.yml         # override: adds Solr and healthy depends
└─ services/
   └─ search-service/
      ├─ Dockerfile                   # Temurin 21 multi-stage
      ├─ build.gradle.kts
      └─ src/main|test/...

---

3) Prerequisites

• macOS with Docker Desktop (or Docker Engine)
• Docker Compose v2
• JDK 21 (Temurin recommended) for local runs
• Gradle wrapper (provided)

---

4) Run locally (no Docker)

From repo root:

./gradlew :services:search-service:bootRun

Check health:

curl -s http://localhost:8080/health | jq
# -> { "ok": true, "service": "search-service", "timestamp": "2025-10-02T20:10:00Z" }

Alternatively (Actuator):

curl -s http://localhost:8080/actuator/health

---

5) Run with Docker

Build and run the container:

docker compose -f infra/docker-compose.yml up --build

Health:

curl -s http://localhost:8080/health
curl -s http://localhost:8080/actuator/health

Stop & clean:

docker compose -f infra/docker-compose.yml down -v

---

6) Configuration

Current service runs with defaults:

• SERVER_PORT (optional): override server port
• Other RAG configs (e.g., SOLR_URL, OLLAMA_BASE_URL) are not used yet Create .env (optional) near infra/docker-compose.yml:

SERVER_PORT=8080

7) Endpoints

• GET /health

Returns JSON with simple service liveness.

• GET /actuator/health

Spring Boot Actuator health.

Example:

curl -s http://localhost:8080/health | jq