🦉 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

./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:

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

# 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

./start.sh

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

3. Tests ausführen

./test.sh

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

4. Logs ansehen

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

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

📋 Alle Befehle im Überblick

🌐 URLs

Nach dem Start erreichbar:

👤 Login Credentials

Admin Account

Email:    admin@crumb.local
Password: admin123

Demo Account

Email:    demo@crumb.local
Password: demo123

🧪 Schnelltest

# 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

# Prüfe Docker Status
docker info

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

Problem: Port bereits belegt

# 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

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

# 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

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

# 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 - Projekt-Übersicht & Architektur
• DIARY_RAG_README.md - Diary RAG System
• compose/README.md - Docker Setup (falls vorhanden)

📚 Document Auto-Indexing

NEU: Markdown-Dokumente werden automatisch beim Start indexiert!

Dokumenten-Ordner

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:

{
  "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:

# 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

# 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

6. Neuer Router: app/routers/my_feature.py
7. In app/main.py mounten
8. Mit docker compose restart app neu laden

💡 Tipps

Schneller Restart

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

Live Logs

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

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

Database Zugriff

# 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

# 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! 💚