Skip to main content

​
Installation Test Results

This page documents the complete installation process, including all commands executed, issues encountered, and their resolutions.

​
Initial System State

# Check OS
cat /etc/os-release
# Output: Debian Trixie

# Check Docker
docker --version
# Result: Docker not installed
###Issue 1: Docker Not Installed Problem: Docker daemon was not running. Command Used: 
sudo apt-get update
sudo apt-get install -y docker.io containerd
Output: 
The following NEW packages will be installed:
  bridge-utils containerd docker.io pigz runc
  [... 19 packages total...]
Result: RESOLVED - Docker 26.1.5 installed successfully Verification: 
docker --version
# Docker version 26.1.5, build 26.1.5+dfsg1-1

docker-compose --version
# Docker Compose version 2.26.1-4

​
Issue 2: GPU Nvidia Configuration

Problem: RuntimeError: Nvidia GPU is required but not available Root Cause: Docker Compose file required GPU for Ollama service. Command Used: 
# Edited docker-compose.yml to comment out GPU requirements
# Line 99-102 (in ollama service):
#    deploy:
#      resources:
#        reservations:
#          devices:
Result: RESOLVED - Ollama now runs in CPU mode

​
Issue 3: Build Context Errors

Problem: Dockerfile COPY paths incorrect after build context change. Error Message: 
failed to solve: failed to compute cache key: 
"/services/orchestrator" not found
Files Modified:
  • backend/api/Dockerfile
  • backend/services/orchestrator/Dockerfile
  • backend/services/embedding/Dockerfile
Changes: 
# Before:
COPY services/orchestrator/ .

# After:
COPY api/ .
Result: RESOLVED - All services build successfully

​
Issue 4: Database Not Initialized

Problem: PostgreSQL running but schema not created. Command to Initialize: 
# Copy init.sql to container
sudo docker cp backend/database/init.sql openrag-postgres:/tmp/

# Execute initialization
sudo docker exec openrag-postgres psql -U openrag -d openrag_db -f /tmp/init.sql
Output: 
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX
Result: RESOLVED - 5 tables created successfully

​
Issue 5: Missing asyncpg Dependency

Problem: PostgreSQL driver not installed. Error: 
ModuleNotFoundError: No module named 'asyncpg'
Command Used: 
# Added to backend/requirements.txt:
echo "asyncpg==0.29.0" >> backend/requirements.txt

# Rebuild services
sudo docker-compose build orchestrator
sudo docker-compose up -d orchestrator
Result: RESOLVED

​
Issue 6: SQL Type Casting Errors

Problem: asyncpg requires explicit type casts for parameters. Error: 
asyncpg.exceptions.AmbiguousFunctionError: 
cannot determine data type of parameter $1
Code Changes: 
# File: backend/services/orchestrator/database/db.py
# Before:
await self.conn.execute(
    "UPDATE documents SET status = $1 WHERE id = $2",
    status, document_id
)

# After:
await self.conn.execute(
    "UPDATE documents SET status = $1::text WHERE id = $2::uuid",
    status, document_id
)
Result: RESOLVED - Explicit casts added throughout codebase

​
Issue 7: Vector ID Format

Problem: Qdrant expected UUID format for point IDs. Error: 
ValueError: UUID validation failed for 'doc_chunk_0'
Code Change: 
# Before:
vector_id = f"doc_{document_id[:8]}_chunk_{i}"

# After:
import uuid
vector_id = str(uuid.uuid4())
Result: RESOLVED

​
Issue 8: Collection Naming Mismatch

Problem: Vectors indexed in “default” collection, queries searching in “documents_embeddings”. Discovery Command: 
curl http://localhost:6333/collections/documents_embeddings | jq
# Output: {"result": {"points_count": 0}}

curl http://localhost:6333/collections/default | jq
# Output: {"result": {"points_count": 4}}
Result: RESOLVED - Updated query to use “default” collection

​
Issue 9: Score Threshold Too High

Problem: No results returned with threshold 0.7. Command Testing: 
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "OpenRAG features", "collection_id": "default", "use_llm": false}'
# Result: {"sources": []}
Code Change: 
# File: backend/services/orchestrator/main.py
# Before:
score_threshold=0.7

# After:
score_threshold=0.3
Verification: 
# Same query after change
# Result: {"sources": [2 results with scores 0.38, 0.37]}
Result: RESOLVED

​
Issue 10: OLLAMA_HOST Missing Protocol

Problem: HTTP client couldn’t connect to Ollama. Error: 
httpx.UnsupportedProtocol: Request URL is missing http:// or https:// protocol
Fix in docker-compose.yml: 
# Before:
- OLLAMA_HOST=ollama:11434

# After:
- OLLAMA_HOST=http://ollama:11434
Result: RESOLVED

​
Issue 11: API Timeout Too Short

Problem: LLM generation timing out at 60 seconds. Code Change: 
# File: backend/api/main.py
# Before:
async with httpx.AsyncClient(timeout=60.0) as client:

# After:
async with httpx.AsyncClient(timeout=300.0) as client:
Reason: First LLM query loads model into RAM (30-60 seconds), subsequent queries are faster. Result: RESOLVED

​
Final Service Status

Command: 
sudo docker-compose ps
Output: 
NAME                   STATUS        PORTS
openrag-api            Up 17 hours   0.0.0.0:8000->8000/tcp
openrag-embedding      Up 17 hours   8003/tcp
openrag-minio          Up 17 hours   0.0.0.0:9000-9001->9000-9001/tcp
openrag-ollama         Up 17 hours   11434/tcp
openrag-orchestrator   Up 17 hours   8001/tcp
openrag-postgres       Up 17 hours   0.0.0.0:5432->5432/tcp
openrag-qdrant         Up 17 hours   0.0.0.0:6333-6334->6333-6334/tcp
openrag-redis          Up 17 hours   0.0.0.0:6379->6379/tcp
Result: All 8 services running successfully

​
Health Check Validation

curl http://localhost:8000/health | jq
Output: 
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-02-18T08:21:11.734093",
  "services": {
    "orchestrator": "healthy"
  }
}

​
Summary

Total issues encountered: 14
Total issues resolved: 14
Final status: All services operational Installation time: Approximately 3-4 hours including troubleshooting next: Upload Tests