MtoRagSystem/INSTALL.md

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:

php -v
php -m

---

1.3 Composer

composer --version

Falls nicht vorhanden:

sudo apt install composer

---

1.4 Datenbank

Version:

• MariaDB 10.11.x (entspricht aktueller ENV)

Installation:

sudo apt install mariadb-server

Datenbank und Benutzer anlegen:

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:

sudo apt install python3 python3-venv python3-pip

Prüfen:

python3 --version

---

1.6 Ollama (LLM Backend)

Installation:

curl -fsSL https://ollama.com/install.sh | sh

Modell bereitstellen:

ollama pull qwen3
oder
ollama pull mto-model (Wenn eigens KI-Model erstellt wurde)

Verfügbarkeit prüfen:

curl http://127.0.0.1:11434/api/tags

---

2. Projektbereitstellung

2.1 Entpacken

unzip rag.zip
cd rag

oder via Git:

git clone <repository>
cd <repository>

---

2.2 PHP-Abhängigkeiten installieren

composer install --no-interaction

Für Produktion:

composer install --no-dev --optimize-autoloader

---

3. Environment-Konfiguration

Datei .env im Projektroot konfigurieren.

3.1 Symfony Core

APP_ENV=dev
APP_SECRET=09333662211af45850ff13d68a40f8e3

Produktion:

APP_ENV=prod

---

3.2 AI Agent Core

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

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:

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

MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0

Queue läuft über Datenbank.

---

3.6 Mailer (optional)

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

php bin/console doctrine:migrations:migrate --no-interaction

---

5. Python Vector Service

5.1 Virtual Environment anlegen

python3 -m venv .venv
source .venv/bin/activate

---

5.2 Abhängigkeiten installieren

Automatisiert:

php bin/console mto:agent:vector:control --install

Alternativ manuell:

pip install fastapi uvicorn sentence-transformers faiss-cpu numpy

CPU-Version von FAISS ist ausreichend.

---

5.3 Vector Service starten

php bin/console mto:agent:vector:control --start

Status prüfen:

php bin/console mto:agent:vector:control --status

---

6. Initialer Reindex

Vor produktiver Nutzung zwingend erforderlich:

php bin/console mto:agent:ingest:global

Ohne Reindex ist kein Retrieval möglich.

---

7. Anwendung starten

Entwicklung:

php -S 127.0.0.1:8000 -t public

Produktion:

• Über Nginx oder Apache bereitstellen
• APP_ENV=prod setzen
• Cache warmup durchführen

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