> ## 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.

# Quick Start

> Launch OpenRAG in 5 minutes

# Quick Start

Install and launch OpenRAG with all its web interfaces in **5 minutes flat**.

## Prerequisites

<CardGroup cols={2}>
  <Card title="Docker 26.0+" icon="docker">
    Installation: [Guide](/installation/requirements#required-software)
  </Card>

  <Card title="Docker Compose 2.26+" icon="layer-group">
    Included with modern Docker
  </Card>

  <Card title="16 GB RAM minimum" icon="memory">
    32 GB recommended with GPU
  </Card>

  <Card title="50 GB storage" icon="hard-drive">
    For Docker images + LLM model (4.9 GB)
  </Card>
</CardGroup>

<Warning>
  **Important:** The system requires **16 GB RAM minimum** to run the llama3.1:8b LLM. See [Detailed Requirements](/installation/requirements) for more information.
</Warning>

## Installation in 4 Steps

### 1. Clone the Repository

```bash theme={null}
git clone https://github.com/3ntrop1a/openrag.git
cd openrag
```

### 2. Launch All Services

```bash theme={null}
# Start all microservices
sudo docker-compose up -d
```

<Accordion title="What does the stack look like? (docker-compose.yml overview)">
  ```yaml theme={null}
  services:
    # Infrastructure
    postgres:          # PostgreSQL 16 — document metadata & query history
    redis:             # Redis 7 — cache & task queue
    minio:             # MinIO — S3-compatible file storage (port 9000/9001)
    qdrant:            # Qdrant — vector database (port 6333)
    ollama:            # Ollama — local LLM server (port 11434)

    # Application
    embedding:         # Sentence-transformer embedding service (port 8002)
    orchestrator:      # RAG pipeline orchestration (port 8001)
    api:               # FastAPI REST gateway (port 8000)
    frontend-nextjs:   # Next.js chat + admin panel (port 3000)

    # Monitoring (optional — started with --profile monitoring)
    prometheus:        # Metrics scraping (port 9090)
    grafana:           # Pre-configured dashboards (port 3002)
  ```

  All services are connected to the `openrag-network` Docker bridge. Only the ports above are exposed to your host — everything else is internal.
</Accordion>

<Info>
  **First startup:** Downloading Docker images and LLM model (4.9 GB). Allow **10-15 minutes** depending on your connection.
</Info>

### 3. Verify Everything is Started

```bash theme={null}
# View the status of the 10 services
sudo docker-compose ps
```

You should see **8 services** with `Up` status:

```
NAME                       STATUS
openrag-api                Up
openrag-orchestrator       Up
openrag-embedding          Up
openrag-postgres           Up
openrag-redis              Up
openrag-minio              Up
openrag-qdrant             Up
openrag-ollama             Up
```

### 4. Download the LLM Model

If you're using Ollama (default configuration):

```bash theme={null}
docker exec -it openrag-ollama ollama pull llama3.1:8b
```

<Tip>
  Lightweight alternatives: `llama3.1:3b` (2GB), `gemma:2b` (1.5GB), `phi3:mini` (2.3GB)
</Tip>

<Info>
  Downloading the llama3.1:8b model takes **4.9 GB**. Allow 5-10 minutes depending on your connection.
</Info>

## Access Web Interfaces

Open your browser and test the interfaces:

<CardGroup cols={2}>
  <Card title="User Chat" icon="messages" href="http://localhost:3000">
    **Main interface** - [http://localhost:3000](http://localhost:3000)

    Next.js + ShadcnUI chat with markdown rendering
  </Card>

  <Card title="API Swagger" icon="code" href="http://localhost:8000/docs">
    **API Documentation** - [http://localhost:8000/docs](http://localhost:8000/docs)

    Test the REST API interactively
  </Card>

  <Card title="Qdrant Dashboard" icon="database" href="http://localhost:6333/dashboard">
    **Vector database** - [http://localhost:6333/dashboard](http://localhost:6333/dashboard)

    Explore indexed vectors
  </Card>
</CardGroup>

## First Test

### Option 1: Via Chat Interface (Recommended)

<Steps>
  <Step title="Open the user interface">
    Navigate to [http://localhost:3000](http://localhost:3000)
  </Step>

  <Step title="Ask a test question">
    In the chat, type:

    ```
    What is OpenRAG and how does it work?
    ```

    Click "Send" or press Enter.
  </Step>

  <Step title="Observe the response">
    The system will:

    1. Search in documents (100-200 ms)
    2. Generate a response with the LLM (5-15 s after first load)
    3. Display sources below with relevance scores

    **Important:** The first query takes **70-90 seconds or more** (loading LLM model into RAM — CPU mode is always slow).
  </Step>
</Steps>

### Option 2: Via REST API (curl)

<Steps>
  <Step title="Check API health">
    ```bash theme={null}
    curl http://localhost:8000/health | jq
    ```

    Expected response:

    ```json theme={null}
    {
      "status": "healthy",
      "timestamp": "2026-02-18T...",
      "version": "1.1.0",
      "services": {
        "database": "healthy",
        "redis": "healthy",
        "vector_store": "healthy",
        "orchestrator": "healthy"
      }
    }
    ```
  </Step>

  <Step title="Do a simple search (without LLM)">
    ```bash theme={null}
    curl -X POST http://localhost:8000/query \
      -H "Content-Type: application/json" \
      -d '{
        "query": "configuration settings",
        "collection_id": "default",
        "max_results": 3,
        "use_llm": false
      }' | jq
    ```

    Returns similar documents with relevance scores.
  </Step>

  <Step title="Make a query with LLM">
    ```bash theme={null}
    curl -X POST http://localhost:8000/query \
      -H "Content-Type: application/json" \
      -d '{
        "query": "What are the main features described in the documentation?",
        "collection_id": "default",
        "max_results": 5,
        "use_llm": true
      }' | jq -r '.answer'
    ```

    <Warning>
      **Every query:** 70-90 seconds or more (CPU-only, llama3.1:8b)
    </Warning>
  </Step>
</Steps>

## Upload Your Own Documents

### Via Admin Interface (Recommended)

<Steps>
  <Step title="Open admin panel">
    [http://localhost:3000/admin](http://localhost:3000/admin)
  </Step>

  <Step title="Go to Upload">
    Click "Upload" in the sidebar
  </Step>

  <Step title="Select a PDF file">
    * Click "Browse files"
    * Choose a PDF
    * Fill in metadata (optional)
    * Click "Upload"
  </Step>

  <Step title="Verify processing">
    * Go to "Documents" section
    * Check status (processing → processed)
    * Allow 10-30 seconds per document depending on size
  </Step>
</Steps>

### Via API

```bash theme={null}
curl -X POST http://localhost:8000/documents/upload \
  -F "file=@my_document.pdf" \
  -F "collection_id=default" \
  -F "metadata={\"category\":\"guide\",\"source\":\"documentation\"}"
```

## MinIO Access (File Storage)

**URL:** [http://localhost:9001](http://localhost:9001)\
**Credentials:** admin / admin123456

<Warning>
  **Important:** Change this password before any production deployment!
</Warning>

## Useful Commands

### View Logs in Real-Time

```bash theme={null}
# All services
sudo docker-compose logs -f

# A specific service
sudo docker-compose logs -f orchestrator
sudo docker-compose logs -f ollama
```

### Restart a Service

```bash theme={null}
sudo docker-compose restart orchestrator
```

### Stop Everything

```bash theme={null}
sudo docker-compose down
```

### Clean Completely (Including Data)

```bash theme={null}
sudo docker-compose down -v  # Also removes volumes
```

<Warning>
  The `-v` option removes all volumes, including your documents and indexed data!
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="System Architecture" icon="diagram-project" href="/architecture">
    Understand OpenRAG's internal workings
  </Card>

  <Card title="Detailed Requirements" icon="list-check" href="/installation/requirements">
    GPU configuration, optimizations, production
  </Card>

  <Card title="Tests & Validation" icon="flask-vial" href="/tests/overview">
    Load tests, performance, quality
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Complete REST API documentation
  </Card>
</CardGroup>

## Quick Troubleshooting

### Services won't start

```bash theme={null}
# Check logs
sudo docker-compose logs -f

# Check disk space (minimum 50 GB)
df -h

# Check RAM (minimum 16 GB)
free -h
```

### Ollama not responding

```bash theme={null}
# Check if model is downloaded
docker exec -it openrag-ollama ollama list

# If absent, download it
docker exec -it openrag-ollama ollama pull llama3.1:8b
```

### Queries very slow (>75s)

<Tip>
  **Solution:** Use a GPU! See [GPU Configuration](/openrag/installation/requirements#gpu-nvidia-recommandé) to go from 70-90s to 1-3s per query.
</Tip>

### No results for queries

```bash theme={null}
# Check if documents are processed
curl http://localhost:8000/documents | jq '.documents[] | {filename, status}'

# Status "processed" = ready
# Status "processing" = in progress (wait 10-30s)
```