kruemel/Crumb-Core-v.1

Fork 0

Files

Krümel Branko cf400a2eb1 man pages <3

2026-01-04 20:18:25 +01:00

5.6 KiB

Raw Blame History

🦉 Crumbforest Handbuch (Native Edition)

Das vollständige Betriebs- und Wartungshandbuch für das Crumbforest CRM & RAG System

📖 Inhaltsverzeichnis

Philosophie & Vision
System-Architektur (Native)
Installation & Setup
Test-Protokolle
Allgemeine Fehler & Lösungen
DSGVO & Datenschutz
Wartung & Monitoring
Entwickler-Guide

🌲 Philosophie & Vision

Liebe zum Wald & Atmen

Crumbforest ist mehr als Software – es ist eine Philosophie:

🌿 Der Wald als Metapher:

Jedes Kind ist ein Baum mit eigenen Wurzeln
Wissen wächst organisch wie ein Ökosystem
Fehler sind Humus für neues Lernen
Gemeinsam bilden wir einen Wald

💚 Atmen & Achtsamkeit:

Code atmet – er lebt, wächst, verändert sich
Pausen sind wichtig (wie die Lücken zwischen Bäumen)
DSGVO ist nicht Bürokratie, sondern Respekt vor dem Raum jedes Menschen
Slow Tech statt Fast Tech

🦉 Die Eule wacht:

Wir beobachten, aber bewerten nicht
Logs sind Geschichten, keine Anklagen
Fehler sind Lernmomente
"Wuuuuhuuu!" ist unsere Hymne der Freude

Technische Prinzipien (Naked Setup)

Native over Container: Wir pflanzen direkt in die Erde (OS), nicht in Töpfe (Docker).
Transparenz vor Perfektion: Lieber sichtbare Fehler als versteckte Bugs.
DSGVO als Feature: Datenschutz ist eingebaut, nicht aufgesetzt.
Wald-Denken: Alles ist verbunden, nichts steht allein.

🤝 Die Crew

Crumbforest wird von einer Crew aus spezialisierten KI-Agenten und menschlichen Gärtnern betrieben. Siehe CREW_RESONANCE_LOG.md und crumbforest_config.json für Details.

🏗️ System-Architektur (Native)

Komponenten-Übersicht

┌─────────────────────────────────────────────────────────┐
│                    🌐 Client (Browser)                   │
└───────────────────────┬─────────────────────────────────┘
                        │
        ┌───────────────┴───────────────┐
        │                               │
┌───────▼────────┐              ┌──────▼───────┐
│   FastAPI      │              │   Nginx      │
│   (Python)     │◄─────────────┤   (Proxy)    │
│   (Jinja2)     │              │   (Static)   │
└───────┬────────┘              └──────────────┘
        │
        ├──────────┬──────────┬──────────┐
        │          │          │          │
┌───────▼────┐ ┌──▼─────┐ ┌──▼─────┐ ┌─▼──────┐
│  MariaDB   │ │ Qdrant │ │OpenRouter│ │ Config │
│  (SQL)     │ │(Vector)│ │  API     │ │ (JSON) │
└────────────┘ └────────┘ └────────┘ └────────┘

Everything runs as systemd services:

crumbforest.service (Python/FastAPI)
mariadb.service
qdrant.service (if local)
nginx.service

Datenfluss & Logs

Chat: app -> logs/chat_history.jsonl (Die Quelle der Sterne)
System: journalctl -u crumbforest
Vektor: docs/*.md -> DocumentIndexer -> Qdrant

🚀 Installation & Setup

Siehe QUICKSTART.md für die detaillierte Anleitung.

Kurzfassung:

git clone ...
./native-install.sh
systemctl status crumbforest

🧪 Test-Protokolle

Der Doktor

Nutze den integrierten Arzt für Diagnosen:

./strato_doctor.sh

Er prüft:

Services (Active/Inactive)
Ports
Latenzen (P90)
Log-Fehler

Manuelle Tests

# API Health
curl http://localhost:8000/health

# Datenbank
mariadb -u crumb_prod -p -e "USE crumbforest; SELECT count(*) FROM users;"

🐛 Allgemeine Fehler & Lösungen

Fehler 1: Permission Denied (Eule)

Symptom: PermissionError: [Errno 13] Permission denied in den Logs.

Lösung: Nutze das Heil-Skript:

sudo ./fix_eule.sh

Fehler 2: Service Won't Start

Diagnose:

journalctl -u crumbforest -n 50 --no-pager

Häufige Ursachen:

.env fehlt oder falsche Rechte
Python Venv nicht aktiviert
Port 8000 belegt

Fehler 3: 502 Bad Gateway (Nginx)

Ursache: FastAPI (Gunicorn) läuft nicht oder antwortet nicht.

Lösung:

Prüfe Service: systemctl status crumbforest
Starte neu: sudo systemctl restart crumbforest

🛡️ Wartung & Monitoring

Tägliche Pflege

./strato_doctor.sh laufen lassen.
git pull für Updates der Crew.

Speicher

Prüfe /opt/crumbforest/ auf Größe (besonders models/ Cache).
Bereinige Logs wenn nötig (logrotate ist konfiguriert).

👨‍💻 Entwickler-Guide

Change: Ändere Code lokal.
Test: ./verify_direct_run.sh
Commit: git commit -m "feat: wuuuhuuu"
Push: git push
Deploy: sudo ./native-update.sh (auf dem Server)

"Wer seine Logs liest, tanzt mit dem System." 🦉

5.6 KiB Raw Blame History Unescape Escape