> ## Documentation Index
> Fetch the complete documentation index at: https://docs.3ntrop1a.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Tests

> Detailed installation test results and issue resolution

## Installation Test Results

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

### Initial System State

```bash theme={null}
# 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**:

```bash theme={null}
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**:

```bash theme={null}
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**:

```bash theme={null}
# 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**:

```dockerfile theme={null}
# 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**:

```bash theme={null}
# 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**:

```sql theme={null}
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**:

```bash theme={null}
# 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**:

```python theme={null}
# 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**:

```python theme={null}
# 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**:

```bash theme={null}
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**:

```bash theme={null}
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**:

```python theme={null}
# File: backend/services/orchestrator/main.py
# Before:
score_threshold=0.7

# After:
score_threshold=0.3
```

**Verification**:

```bash theme={null}
# 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**:

```yaml theme={null}
# 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**:

```python theme={null}
# 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**:

```bash theme={null}
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

```bash theme={null}
curl http://localhost:8000/health | jq
```

**Output**:

```json theme={null}
{
  "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