fix: restore default docs (Handbuch, Quickstart)
This commit is contained in:
2
.gitignore
vendored
2
.gitignore
vendored
@@ -30,8 +30,6 @@ dev_docs.bak
|
||||
|
||||
# Decoupled Documentation (Content)
|
||||
docs/
|
||||
HANDBUCH.md
|
||||
QUICKSTART.md
|
||||
CrumbTech.md
|
||||
ARCHITECTURE_ROLES_GROUPS.md
|
||||
QDRANT_ACCESS.md
|
||||
|
||||
1492
HANDBUCH.md
Normal file
1492
HANDBUCH.md
Normal file
File diff suppressed because it is too large
Load Diff
395
QUICKSTART.md
Normal file
395
QUICKSTART.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 🦉 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! 💚**
|
||||
@@ -8,8 +8,6 @@
|
||||
echo "🧹 Stripping proprietary content from repository..."
|
||||
|
||||
FILES_TO_REMOVE=(
|
||||
"HANDBUCH.md"
|
||||
"QUICKSTART.md"
|
||||
"CrumbTech.md"
|
||||
"ARCHITECTURE_ROLES_GROUPS.md"
|
||||
"QDRANT_ACCESS.md"
|
||||
|
||||
Reference in New Issue
Block a user