Crumb-Core-v.1/QUICKSTART.md

# 🦉 Crumbforest Quickstart

Schneller Einstieg in 3 Minuten!

## 📦 Voraussetzungen

- **Docker** & **Docker Compose** installiert
- **Python 3** (optional, für Tests)
- Mindestens ein **API Key** (OpenAI, Anthropic oder OpenRouter)

## 🚀 Installation

### 1. Setup ausführen

```bash
./setup.sh
```

Das Skript:
- ✅ Prüft alle Dependencies
- ✅ Erstellt `.env` Datei
- ✅ Baut Docker Images
- ✅ Startet alle Services
- ✅ Initialisiert Datenbank
- ✅ Verifiziert Installation

**Wichtig:** Trage deine API Keys in `compose/.env` ein:
```bash
# OpenRouter (empfohlen - unterstützt Embeddings + Completions)
OPENROUTER_API_KEY=sk-or-v1-...

# Oder einzelne Provider:
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

**Tipp:** OpenRouter ist am flexibelsten - ein Key für Embeddings (OpenAI) UND Completions (Claude)!

**⚠️ WICHTIG:** Prüfe/setze diese Provider-Einstellungen in `compose/.env`:
```bash
# RAG Configuration - KORREKTE Einstellungen!
DEFAULT_EMBEDDING_PROVIDER=openrouter    # NICHT openai!
DEFAULT_EMBEDDING_MODEL=text-embedding-3-small
DEFAULT_COMPLETION_PROVIDER=openrouter
DEFAULT_COMPLETION_MODEL=anthropic/claude-3-5-sonnet
```

### 2. System starten

```bash
./start.sh
```

Startet alle Container und wartet, bis alle Services bereit sind.

### 3. Tests ausführen

```bash
./test.sh
```

Wähle aus:
- **Quick Test** - Basis-Tests (Health, API, DB)
- **Integration Test** - Kompletter RAG Flow
- **Alle Tests** - Quick + Integration

### 4. Logs ansehen

```bash
./logs.sh app         # FastAPI Logs
./logs.sh db          # MariaDB Logs
./logs.sh all         # Alle Logs
./logs.sh app -f      # FastAPI Logs (follow)
```

### 5. System stoppen

```bash
./stop.sh              # Stoppe Container
./stop.sh --remove     # Stoppe + entferne Container
./stop.sh --clean      # Stoppe + lösche ALLE Daten (⚠️)
```

## 📋 Alle Befehle im Überblick

| Befehl | Beschreibung |
|--------|--------------|
| `./setup.sh` | Komplettes Setup (nur einmal) |
| `./start.sh` | System starten |
| `./stop.sh` | System stoppen |
| `./test.sh` | Tests ausführen |
| `./logs.sh [service]` | Logs ansehen |

## 🌐 URLs

Nach dem Start erreichbar:

| Service | URL | Beschreibung |
|---------|-----|--------------|
| FastAPI | http://localhost:8000 | Hauptanwendung |
| Admin Login | http://localhost:8000/de/login | Admin Interface |
| API Docs | http://localhost:8000/docs | Swagger UI |
| Qdrant UI | http://localhost:6333/dashboard | Vector DB UI |

## 👤 Login Credentials

### Admin Account
```
Email:    admin@crumb.local
Password: admin123
```

### Demo Account
```
Email:    demo@crumb.local
Password: demo123
```

## 🧪 Schnelltest

```bash
# Health Check
curl http://localhost:8000/health

# Alle Routes
curl http://localhost:8000/__routes

# Provider Status
curl http://localhost:8000/admin/rag/providers

# Whoami
curl http://localhost:8000/__whoami
```

## 🔧 Troubleshooting

### Problem: Docker läuft nicht
```bash
# Prüfe Docker Status
docker info

# Starte Docker Desktop (macOS/Windows)
# oder Docker Daemon (Linux)
sudo systemctl start docker
```

### Problem: Port bereits belegt
```bash
# Prüfe welcher Prozess Port 8000 nutzt
lsof -i :8000

# Oder ändere den Port in docker-compose.yml
ports:
  - "8001:8000"  # Nutze Port 8001 statt 8000
```

### Problem: API Keys fehlen
```bash
# Öffne .env und füge Keys ein
nano compose/.env

# Oder setze sie als Environment Variables
export OPENAI_API_KEY=sk-...
./start.sh
```

### Problem: Database Connection Failed
```bash
# Prüfe DB Logs
./logs.sh db

# Warte länger auf DB
docker compose -f compose/docker-compose.yml exec -T db sh -c \
  'mariadb -u$MARIADB_USER -p$MARIADB_PASSWORD $MARIADB_DATABASE -e "SELECT 1"'

# Neustart erzwingen
./stop.sh --remove
./start.sh
```

### Problem: FastAPI startet nicht
```bash
# Prüfe App Logs
./logs.sh app -f

# Häufigste Ursachen:
# - Port belegt
# - Dependencies fehlen
# - Syntax Error in Code

# Rebuild erzwingen
cd compose
docker compose build --no-cache app
docker compose up -d
```

### ⚠️ KRITISCH: Code-Änderungen erfordern Rebuild!

**Es gibt KEIN Volume Mount für App-Code!** Der Code ist im Docker Image eingebacken.

```bash
# Nach JEDER Code-Änderung in app/:
cd compose
docker compose up --build -d

# Bei größeren Änderungen (Clean Build):
docker compose down
docker compose up --build -d
```

**Was erfordert einen Rebuild:**
- ✅ Änderungen in `app/*.py`
- ✅ Änderungen in `app/routers/*.py`
- ✅ Änderungen in `app/lib/**/*.py`
- ✅ Änderungen in `app/services/*.py`
- ✅ Änderungen in `app/requirements.txt`
- ❌ Änderungen in `compose/.env` (nur Restart)
- ❌ Änderungen in `docs/*.md` (nur Restart für Re-Index)

## 📚 Weitere Dokumentation

- **[CLAUDE.md](CLAUDE.md)** - Projekt-Übersicht & Architektur
- **[DIARY_RAG_README.md](DIARY_RAG_README.md)** - Diary RAG System
- **[compose/README.md](compose/README.md)** - Docker Setup (falls vorhanden)

## 📚 Document Auto-Indexing

**NEU:** Markdown-Dokumente werden automatisch beim Start indexiert!

### Dokumenten-Ordner

```bash
docs/
  ├── rz-nullfeld/      # RZ Nullfeld Dokumentation
  └── crumbforest/      # Crumbforest Dokumentation
```

### Automatischer Index

Beim Docker-Start werden alle `.md` Dateien:
- ✅ Automatisch in Qdrant indexiert
- ✅ Mit File-Hash-Tracking (nur bei Änderungen)
- ✅ In separate Collections sortiert
- ✅ DSGVO-konform geloggt

### Qdrant Collections

Nach dem Start verfügbar:
- **docs_rz_nullfeld_** - RZ Nullfeld Docs
- **docs_crumbforest_** - Crumbforest Docs
- **diary_child_{id}_** - Kinder-Tagebücher

### Dokumente durchsuchen

**Im Browser (nach Login):**
```
http://localhost:8000/api/documents/search?q=Docker&limit=5
http://localhost:8000/api/documents/search?q=Python&limit=5
http://localhost:8000/api/documents/search?q=Qdrant&limit=5
```

**Beispiel-Response:**
```json
{
  "query": "Docker",
  "results": [
    {
      "post_id": 2032991606,
      "title": "ssh_login_test",
      "header": "Dockerfile Ergänzung",
      "content": "## 2. 🌧️ Dockerfile Ergänzung\n\n```Dockerfile",
      "score": 0.5505129,
      "collection": "docs_crumbforest"
    },
    {
      "post_id": 676631428,
      "title": "crumbforest_specialist_roles",
      "header": "🐋 DockerDuke – Container-Kapitän",
      "content": "## 🐋 DockerDuke – Container-Kapitän\n**#duke #docker**...",
      "score": 0.5469476,
      "collection": "docs_crumbforest"
    }
  ],
  "provider": "openrouter"
}
```

**Via cURL:**
```bash
# Suche in allen Dokumenten
curl -X GET "http://localhost:8000/api/documents/search?q=docker&limit=5" \
  -H "Cookie: session=..."

# Suche nur in Crumbforest Docs
curl -X GET "http://localhost:8000/api/documents/search?q=terminal&category=crumbforest" \
  -H "Cookie: session=..."

# Indexing Status prüfen
curl -X GET "http://localhost:8000/api/documents/status" \
  -H "Cookie: session=..."
```

### Manuell Re-Indexieren

```bash
# Alle Dokumente neu indexieren
curl -X POST "http://localhost:8000/api/documents/index" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=..." \
  -d '{"provider": "openrouter", "force": true}'

# Nur eine Kategorie
curl -X POST "http://localhost:8000/api/documents/index" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=..." \
  -d '{"category": "crumbforest", "provider": "openrouter"}'
```

## 🎯 Nächste Schritte

1. **Admin UI erkunden**
   ```bash
   open http://localhost:8000/de/login
   ```

2. **API testen**
   ```bash
   ./test.sh
   ```

3. **Dokumente durchsuchen**
   ```bash
   # Nach Docker-Start sind ~286 Markdown-Dateien indexiert
   curl http://localhost:6333/collections
   ```

4. **Diary RAG testen**
   ```bash
   # Siehe DIARY_RAG_README.md für Beispiele
   curl -X POST http://localhost:8000/api/diary/index ...
   ```

5. **Eigene Features entwickeln**
   - Neuer Router: `app/routers/my_feature.py`
   - In `app/main.py` mounten
   - Mit `docker compose restart app` neu laden

## 💡 Tipps

### Schneller Restart
```bash
# Nur App Container neustarten (schneller)
docker compose -f compose/docker-compose.yml restart app
```

### Live Logs
```bash
# Alle Logs in Echtzeit
./logs.sh all -f

# Nur Errors
./logs.sh app -f | grep ERROR
```

### Database Zugriff
```bash
# MySQL Shell
docker compose -f compose/docker-compose.yml exec db \
  mariadb -u crumb -p crumbforest

# Query ausführen
docker compose -f compose/docker-compose.yml exec -T db sh -c \
  'mariadb -u$MARIADB_USER -p$MARIADB_PASSWORD $MARIADB_DATABASE \
  -e "SELECT * FROM users;"'
```

### Qdrant Zugriff
```bash
# Collections listen
curl http://localhost:6333/collections

# Collection Details
curl http://localhost:6333/collections/diary_child_1
```

## 🦉 Wuuuuhuuu!

Das wars! Du bist bereit loszulegen.

Bei Fragen oder Problemen:
1. Prüfe die Logs: `./logs.sh app -f`
2. Schaue in CLAUDE.md für Details
3. Führe Tests aus: `./test.sh`

**Happy Coding! 💚**