add new guide files

INSTALL.md

@@ -0,0 +1,402 @@
+# RAG-System – Enterprise Installationsanleitung
+
+Stand: Februar 2026  
+Architektur: Symfony (PHP 8.2+) + MariaDB 10.11 + Python Vector Service (FAISS) + Ollama LLM  
+Betriebsmodus: On-Prem / Containerfähig / CPU-basiert
+
+Diese Anleitung beschreibt eine vollständige Neuinstallation auf sauberer Infrastruktur.
+
+---
+
+# 1. Systemvoraussetzungen
+
+## 1.1 Betriebssystem
+
+Empfohlen:
+- Ubuntu 22.04 LTS (Server)
+
+Alternativ:
+- Debian 12
+- macOS (Entwicklung)
+- Windows nur via WSL2
+
+---
+
+## 1.2 PHP
+
+Version:
+- PHP 8.2 oder höher
+
+Erforderliche Extensions:
+- pdo
+- pdo_mysql
+- mbstring
+- intl
+- curl
+- json
+- zip
+
+Prüfung:
+
+```bash
+php -v
+php -m
+```
+
+---
+
+## 1.3 Composer
+
+```bash
+composer --version
+```
+
+Falls nicht vorhanden:
+
+```bash
+sudo apt install composer
+```
+
+---
+
+## 1.4 Datenbank
+
+Version:
+- MariaDB 10.11.x (entspricht aktueller ENV)
+
+Installation:
+
+```bash
+sudo apt install mariadb-server
+```
+
+Datenbank und Benutzer anlegen:
+
+```sql
+CREATE DATABASE db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'db'@'%' IDENTIFIED BY 'db';
+GRANT ALL PRIVILEGES ON db.* TO 'db'@'%';
+FLUSH PRIVILEGES;
+```
+
+---
+
+## 1.5 Python
+
+Version:
+- Python 3.10 oder höher
+
+Installation:
+
+```bash
+sudo apt install python3 python3-venv python3-pip
+```
+
+Prüfen:
+
+```bash
+python3 --version
+```
+
+---
+
+## 1.6 Ollama (LLM Backend)
+
+Installation:
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+Modell bereitstellen:
+
+```bash
+ollama pull qwen3
+oder
+ollama pull mto-model (Wenn eigens KI-Model erstellt wurde)
+```
+
+Verfügbarkeit prüfen:
+
+```bash
+curl http://127.0.0.1:11434/api/tags
+```
+
+---
+
+# 2. Projektbereitstellung
+
+## 2.1 Entpacken
+
+```bash
+unzip rag.zip
+cd rag
+```
+
+oder via Git:
+
+```bash
+git clone <repository>
+cd <repository>
+```
+
+---
+
+## 2.2 PHP-Abhängigkeiten installieren
+
+```bash
+composer install --no-interaction
+```
+
+Für Produktion:
+
+```bash
+composer install --no-dev --optimize-autoloader
+```
+
+---
+
+# 3. Environment-Konfiguration
+
+Datei `.env` im Projektroot konfigurieren.
+
+## 3.1 Symfony Core
+
+```env
+APP_ENV=dev
+APP_SECRET=09333662211af45850ff13d68a40f8e3
+```
+
+Produktion:
+
+```env
+APP_ENV=prod
+```
+
+---
+
+## 3.2 AI Agent Core
+
+```env
+AI_LLM_API_URL=http://host.docker.internal:11434/api/generate
+AI_LLM_MODEL=mto-model
+AI_LLM_TIMEOUT=600
+
+AI_HISTORY_DIR=var/agent-history
+AI_CONTEXT_LINES=20
+AI_CONTEXT_LINES_FULL=500
+```
+
+Hinweise:
+- Timeout unter 600 Sekunden wird nicht empfohlen.
+- API-URL an Infrastruktur anpassen (Docker vs. Localhost).
+
+---
+
+## 3.3 Debug-Konfiguration
+
+```env
+AI_DEBUG=false
+AI_LOG_PROMPT=false
+AI_LOG_CONTEXT=false
+```
+
+In Entwicklungsumgebung optional aktivieren.
+
+---
+
+## 3.4 Datenbank (aktive Konfiguration)
+
+Nur diese DATABASE_URL verwenden:
+
+```env
+DATABASE_URL="mysql://db:db@db:3306/db?sslmode=disable&charset=utf8mb4&serverVersion=10.11.0-mariadb"
+DATABASE_VERSION="10.11.0-mariadb"
+DATABASE_DRIVER="mysql"
+DATABASE_HOST="db"
+DATABASE_PORT="3306"
+DATABASE_USER="db"
+DATABASE_PASSWORD="db"
+DATABASE_NAME="db"
+DATABASE_SERVER="mysql://db:3306"
+```
+
+Wichtig:
+- PostgreSQL-Konfiguration entfernen.
+- Nur eine DATABASE_URL definieren.
+
+---
+
+## 3.5 Messenger
+
+```env
+MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
+```
+
+Queue läuft über Datenbank.
+
+---
+
+## 3.6 Mailer (optional)
+
+```env
+MAILER_DSN="smtp://127.0.0.1:1025"
+MAILER_HOST="127.0.0.1"
+MAILER_PORT="1025"
+MAILER_DRIVER="smtp"
+MAILER_AUTH_MODE=""
+MAILER_USERNAME=""
+MAILER_PASSWORD=""
+MAILER_CATCHER="1"
+MAILER_WEB_URL="https://rag.ddev.site:8026"
+```
+
+Nur relevant wenn Mailfunktionen aktiv genutzt werden.
+
+---
+
+# 4. Datenbankmigration
+
+```bash
+php bin/console doctrine:migrations:migrate --no-interaction
+```
+
+---
+
+# 5. Python Vector Service
+
+## 5.1 Virtual Environment anlegen
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+---
+
+## 5.2 Abhängigkeiten installieren
+
+Automatisiert:
+
+```bash
+php bin/console mto:agent:vector:control --install
+```
+
+Alternativ manuell:
+
+```bash
+pip install fastapi uvicorn sentence-transformers faiss-cpu numpy
+```
+
+CPU-Version von FAISS ist ausreichend.
+
+---
+
+## 5.3 Vector Service starten
+
+```bash
+php bin/console mto:agent:vector:control --start
+```
+
+Status prüfen:
+
+```bash
+php bin/console mto:agent:vector:control --status
+```
+
+---
+
+# 6. Initialer Reindex
+
+Vor produktiver Nutzung zwingend erforderlich:
+
+```bash
+php bin/console mto:agent:ingest:global
+```
+
+Ohne Reindex ist kein Retrieval möglich.
+
+---
+
+# 7. Anwendung starten
+
+Entwicklung:
+
+```bash
+php -S 127.0.0.1:8000 -t public
+```
+
+Produktion:
+- Über Nginx oder Apache bereitstellen
+- APP_ENV=prod setzen
+- Cache warmup durchführen
+
+```bash
+php bin/console cache:clear --env=prod
+php bin/console cache:warmup --env=prod
+```
+
+---
+
+# 8. Funktionstest
+
+1. Datenbank erreichbar
+2. Migration erfolgreich
+3. Vector Service aktiv
+4. Ollama erreichbar
+5. Global Reindex durchgeführt
+6. Dokument hochgeladen
+7. Version aktiviert
+8. Chat liefert Antwort
+
+---
+
+# 9. Betriebsrelevante Hinweise
+
+## Modellwechsel
+
+Bei Änderung von:
+- AI_LLM_MODEL
+
+Kein Reindex erforderlich.
+
+Bei Änderung von:
+- Embedding-Modell (Python-Seite)
+- Embedding-Dimension
+- Chunking-Parametern
+
+Global Reindex zwingend erforderlich.
+
+---
+
+## NDJSON und Vector Index
+
+Speicherort:
+```
+var/vector/
+```
+
+Nicht manuell verändern.  
+Index ist deterministisch und wird vollständig neu aufgebaut.
+
+---
+
+## Produktionsbetrieb
+
+Empfohlen:
+- Reverse Proxy (Nginx)
+- Systemd Service für Vector Service
+- Eigener Service für Ollama
+- Backup von Datenbank + var/vector/
+
+---
+
+# Installation abgeschlossen
+
+Das System ist betriebsbereit für:
+
+- Versionierte Dokumentverwaltung
+- Deterministischen NDJSON-Ingest
+- FAISS-Vektorindex
+- Hybrid Retrieval
+- LLM-gestützte Antwortgenerierung