From 66c7ac500b93cf5d019eccaf9ff3bdf8767708d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kr=C3=BCmel=20Branko?= Date: Fri, 2 Jan 2026 22:10:34 +0100 Subject: [PATCH] schnell ist oftmals langsam <3 --- QUICKSTART.md | 407 +++++--------------------------------------------- 1 file changed, 38 insertions(+), 369 deletions(-) diff --git a/QUICKSTART.md b/QUICKSTART.md index e090fb3..a4bed8e 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,395 +1,64 @@ -# 🦉 Crumbforest Quickstart +# 🦉 Crumbforest Quickstart (Native Edition) -Schneller Einstieg in 3 Minuten! +**"Naked Setup"** – Direkte Installation auf Debian/Linux. Kein Docker. Keine Abstraktion. Echte Maschinen. ## 📦 Voraussetzungen -- **Docker** & **Docker Compose** installiert -- **Python 3** (optional, für Tests) -- Mindestens ein **API Key** (OpenAI, Anthropic oder OpenRouter) +- **Debian 12+** Server +- **Root/Sudo** Zugriff +- Eine **feste IP** oder Domain (z.B. via `sslip.io`) -## 🚀 Installation - -### 1. Setup ausführen +## 🚀 Installation in 3 Schritten +### 1. Repository klonen ```bash -./setup.sh +cd /opt +git clone https://github.com/YOUR_USER/crumbcrm_crumbcore_v1.git crumbforest +cd crumbforest ``` -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: +### 2. Native Installer starten +Das Skript erledigt alles: Python venv, MariaDB Setup, Nginx Config & Systemd Services. ```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-... +sudo ./native_crumbcore_v1/native-install.sh ``` -**Tipp:** OpenRouter ist am flexibelsten - ein Key für Embeddings (OpenAI) UND Completions (Claude)! - -**⚠️ WICHTIG:** Prüfe/setze diese Provider-Einstellungen in `compose/.env`: +### 3. Diagnose & Start +Prüfe, ob der Wald atmet: ```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 +sudo ./native_crumbcore_v1/strato_doctor.sh ``` -### 2. System starten +--- +## 🛠️ Tägliche Arbeit + +### Updates einspielen +Niemals einfach überschreiben! Nutze den Updater für Backups & Clean Restart: ```bash -./start.sh +git pull +sudo ./native_crumbcore_v1/native-update.sh ``` -Startet alle Container und wartet, bis alle Services bereit sind. - -### 3. Tests ausführen +### Logs lesen ("Der Wald spricht") +- **Diagnose:** `sudo ./native_crumbcore_v1/strato_doctor.sh` +- **Live Logs:** `sudo journalctl -u crumbforest -f` +- **Handbuch:** `native_crumbcore_v1/log_analyse_handbuch.md` +### Berechtigungen reparieren (Notfall) +Wenn die Eule oder Cache zickt: ```bash -./test.sh +sudo ./native_crumbcore_v1/fix_eule.sh ``` -Wähle aus: -- **Quick Test** - Basis-Tests (Health, API, DB) -- **Integration Test** - Kompletter RAG Flow -- **Alle Tests** - Quick + Integration +--- -### 4. Logs ansehen +## 💡 Warum Native? +Wir nutzen kein Docker, weil wir **lernen** wollen. +- Wir wollen sehen, wie `systemd` einen Service am Leben hält. +- Wir wollen verstehen, wie `nginx` Requests weiterleitet. +- Wir wollen, dass unsere Logs direkt im Journal landen, nicht in einem Container-Overlay. -```bash -./logs.sh app # FastAPI Logs -./logs.sh db # MariaDB Logs -./logs.sh all # Alle Logs -./logs.sh app -f # FastAPI Logs (follow) -``` +Lies **[native_crumbcore_v1/FIRST_STEPS_FOR_GARDENERS.md](native_crumbcore_v1/FIRST_STEPS_FOR_GARDENERS.md)** für die Philosophie dahinter. -### 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! 💚** +**Happy Gardening! 🌲💚**