diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..b5c2aa5 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,515 @@ +# FAQ - Häufig gestellte Fragen + +Antworten auf häufig gestellte Fragen zum Customer Installer System. + +## 🎯 Allgemein + +### Was ist der Customer Installer? + +Der Customer Installer ist ein automatisiertes Deployment-System für RAG (Retrieval-Augmented Generation) Stacks auf Proxmox VE. Es erstellt LXC-Container mit PostgreSQL, PostgREST, n8n und Ollama-Integration. + +### Für wen ist das System gedacht? + +- Entwickler, die schnell RAG-Systeme deployen möchten +- Unternehmen, die KI-Chatbots mit eigenem Wissen betreiben wollen +- Teams, die Workflow-Automation mit KI kombinieren möchten + +### Welche Voraussetzungen gibt es? + +- Proxmox VE Server (7.x oder 8.x) +- Root-Zugriff +- Netzwerk-Konfiguration (Bridge, optional VLAN) +- Optional: Ollama-Server für KI-Modelle + +## 🚀 Installation + +### Wie lange dauert die Installation? + +Eine typische Installation dauert 5-10 Minuten, abhängig von: +- Netzwerk-Geschwindigkeit (Template-Download) +- Server-Performance +- APT-Proxy-Verfügbarkeit + +### Kann ich mehrere Container installieren? + +Ja! Jede Installation erstellt einen neuen Container mit eindeutiger CTID. Sie können beliebig viele Container parallel betreiben. + +```bash +# Container 1 +./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90 + +# Container 2 +./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90 + +# Container 3 +./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90 +``` + +### Wie funktioniert die CTID-Generierung? + +Die CTID wird automatisch generiert basierend auf dem aktuellen Unix-Timestamp. Dies garantiert Eindeutigkeit für die nächsten 10 Jahre. + +```bash +# Format: 7XXXXXXXXX (10 Stellen) +# Beispiel: 769276659 +``` + +### Kann ich eine eigene CTID angeben? + +Ja, mit dem `--ctid` Parameter: + +```bash +./install.sh --ctid 100 --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90 +``` + +**Achtung:** Stellen Sie sicher, dass die CTID nicht bereits verwendet wird! + +## 🔧 Konfiguration + +### Welche Ressourcen werden standardmäßig verwendet? + +- **CPU:** Unlimited +- **RAM:** 4096 MB +- **Swap:** 512 MB +- **Disk:** 50 GB +- **Netzwerk:** DHCP, VLAN 90 + +### Kann ich die Ressourcen anpassen? + +Ja, alle Ressourcen sind konfigurierbar: + +```bash +./install.sh \ + --cores 4 \ + --memory 8192 \ + --swap 1024 \ + --disk 100 \ + --storage local-zfs \ + --bridge vmbr0 \ + --ip dhcp \ + --vlan 90 +``` + +### Wie verwende ich eine statische IP? + +```bash +./install.sh \ + --storage local-zfs \ + --bridge vmbr0 \ + --ip 192.168.45.100/24 \ + --vlan 90 +``` + +### Kann ich VLAN deaktivieren? + +Ja, setzen Sie `--vlan 0`: + +```bash +./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 0 +``` + +## 🔐 Credentials + +### Wo werden die Credentials gespeichert? + +Automatisch in `credentials/sb-.json` nach erfolgreicher Installation. + +### Wie kann ich Credentials später ändern? + +Mit dem `update_credentials.sh` Script: + +```bash +./update_credentials.sh \ + --ctid 769276659 \ + --ollama-url http://ollama.local:11434 \ + --n8n-password "NewPassword123" +``` + +### Sind die Credentials sicher? + +Ja: +- Gespeichert in `.gitignore`-geschütztem Verzeichnis +- Nicht im Git-Repository +- Nur auf dem Proxmox-Host zugänglich +- Passwörter werden automatisch generiert (14+ Zeichen) + +### Wie kann ich das n8n-Passwort zurücksetzen? + +```bash +pct exec -- docker exec n8n \ + n8n user-management:reset \ + --email=admin@userman.de \ + --password=NewPassword123 +``` + +## 🐳 Docker & Container + +### Welche Docker-Container werden erstellt? + +1. **customer-postgres** - PostgreSQL 16 mit pgvector +2. **customer-postgrest** - PostgREST API +3. **n8n** - Workflow-Automation + +### Wie kann ich in einen Container einloggen? + +```bash +# In LXC-Container +pct enter + +# In Docker-Container +pct exec -- docker exec -it n8n sh +pct exec -- docker exec -it customer-postgres bash +``` + +### Wie starte ich Container neu? + +```bash +# Einzelner Docker-Container +pct exec -- docker compose -f /opt/customer-stack/docker-compose.yml restart n8n + +# Alle Docker-Container +pct exec -- docker compose -f /opt/customer-stack/docker-compose.yml restart + +# LXC-Container +pct restart +``` + +### Wie stoppe ich Container? + +```bash +# Docker-Container stoppen +pct exec -- docker compose -f /opt/customer-stack/docker-compose.yml down + +# LXC-Container stoppen +pct stop +``` + +## 📊 Datenbank + +### Welche PostgreSQL-Version wird verwendet? + +PostgreSQL 16 (Alpine-basiert) + +### Ist pgvector installiert? + +Ja, pgvector v0.5.1 ist vorinstalliert und konfiguriert. + +### Wie kann ich auf die Datenbank zugreifen? + +```bash +# Via Docker +pct exec -- docker exec -it customer-postgres \ + psql -U customer -d customer + +# Credentials aus Datei +cat credentials/sb-*.json | jq -r '.postgres' +``` + +### Wie groß ist die Embedding-Dimension? + +384 Dimensionen (für nomic-embed-text Modell) + +### Kann ich die Dimension ändern? + +Ja, aber Sie müssen: +1. Tabelle neu erstellen +2. Anderes Embedding-Modell verwenden +3. Alle Dokumente neu embedden + +```sql +-- Neue Dimension (z.B. 768 für andere Modelle) +CREATE TABLE documents ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + content TEXT NOT NULL, + metadata JSONB, + embedding vector(768), -- Geänderte Dimension + created_at TIMESTAMPTZ DEFAULT NOW() +); +``` + +## 🤖 n8n & Workflows + +### Welcher Workflow wird installiert? + +Der "RAG KI-Bot" Workflow mit: +- Chat-Webhook +- Document-Upload-Form +- Vektor-Embedding +- Similarity-Search +- Chat-Completion + +### Wie kann ich den Workflow anpassen? + +1. Via n8n Web-Interface: `http://:5678` +2. Login mit Credentials aus `credentials/sb-*.json` +3. Workflow bearbeiten und speichern + +### Wird der Workflow bei Neustart geladen? + +Ja, automatisch via `n8n-workflow-reload.service` + +### Wie kann ich eigene Workflows importieren? + +```bash +# Workflow-Datei angeben bei Installation +./install.sh \ + --workflow-file /path/to/my-workflow.json \ + --storage local-zfs \ + --bridge vmbr0 \ + --ip dhcp \ + --vlan 90 +``` + +### Wie viele Workflows kann ich haben? + +Unbegrenzt! Sie können beliebig viele Workflows in n8n erstellen. + +## 🔗 API & Integration + +### Welche APIs sind verfügbar? + +1. **n8n API** - `http://:5678/rest/*` +2. **PostgREST API** - `http://:3000/*` +3. **Chat-Webhook** - `http://:5678/webhook/rag-chat-webhook/chat` +4. **Upload-Form** - `http://:5678/form/rag-upload-form` + +### Wie authentifiziere ich mich bei der API? + +**n8n API:** +```bash +# Login +curl -X POST http://:5678/rest/login \ + -H "Content-Type: application/json" \ + -d '{"emailOrLdapLoginId":"admin@userman.de","password":"..."}' +``` + +**PostgREST API:** +```bash +# Mit API-Key +curl http://:3000/documents \ + -H "apikey: ${ANON_KEY}" \ + -H "Authorization: Bearer ${ANON_KEY}" +``` + +### Ist die API öffentlich zugänglich? + +Standardmäßig nur im lokalen Netzwerk. Für öffentlichen Zugriff: +1. NGINX Reverse Proxy einrichten +2. SSL-Zertifikat konfigurieren +3. Firewall-Regeln anpassen + +### Wie teste ich die Chat-API? + +```bash +curl -X POST http://:5678/webhook/rag-chat-webhook/chat \ + -H "Content-Type: application/json" \ + -d '{"query":"Was ist RAG?"}' +``` + +## 🤖 Ollama-Integration + +### Muss ich Ollama selbst installieren? + +Ja, Ollama läuft auf einem separaten Server. Der Customer Installer verbindet sich nur damit. + +### Welche Ollama-Modelle werden verwendet? + +Standardmäßig: +- **Chat:** ministral-3:3b +- **Embeddings:** nomic-embed-text:latest + +### Kann ich andere Modelle verwenden? + +Ja: + +```bash +# Bei Installation +./install.sh \ + --ollama-model llama2:latest \ + --embedding-model all-minilm:latest \ + --storage local-zfs \ + --bridge vmbr0 \ + --ip dhcp \ + --vlan 90 + +# Nach Installation +./update_credentials.sh \ + --ctid \ + --ollama-model llama2:latest \ + --embedding-model all-minilm:latest +``` + +### Wie ändere ich die Ollama-URL? + +```bash +./update_credentials.sh \ + --ctid \ + --ollama-url http://ollama.local:11434 +``` + +### Funktioniert es ohne Ollama? + +Nein, Ollama ist erforderlich für: +- Text-Embeddings +- Chat-Completions + +Sie können aber alternative APIs verwenden, indem Sie den n8n-Workflow anpassen. + +## 🧪 Testing + +### Wie teste ich die Installation? + +```bash +./test_complete_system.sh +``` + +### Was wird getestet? + +- Container-Status +- Docker-Installation +- Datenbank-Konnektivität +- API-Endpoints +- Workflow-Status +- Credentials +- Netzwerk-Konfiguration + +### Wie lange dauern die Tests? + +Ca. 90 Sekunden für alle 40+ Tests. + +### Was mache ich bei fehlgeschlagenen Tests? + +1. Test-Output analysieren +2. [Troubleshooting](Troubleshooting.md) konsultieren +3. Logs prüfen +4. Bei Bedarf Issue erstellen + +## 🔄 Updates & Wartung + +### Wie aktualisiere ich das System? + +```bash +# Docker-Images aktualisieren +pct exec -- docker compose -f /opt/customer-stack/docker-compose.yml pull +pct exec -- docker compose -f /opt/customer-stack/docker-compose.yml up -d + +# System-Updates +pct exec -- apt-get update +pct exec -- apt-get upgrade -y +``` + +### Wie sichere ich Daten? + +```bash +# Volumes sichern +pct exec -- tar -czf /tmp/backup.tar.gz \ + /opt/customer-stack/volumes/ + +# Backup herunterladen +pct pull /tmp/backup.tar.gz ./backup-$(date +%Y%m%d).tar.gz +``` + +### Wie stelle ich Daten wieder her? + +```bash +# Backup hochladen +pct push ./backup-20260124.tar.gz /tmp/backup.tar.gz + +# Volumes wiederherstellen +pct exec -- tar -xzf /tmp/backup.tar.gz -C / +``` + +### Wie lösche ich einen Container? + +```bash +# Container stoppen +pct stop + +# Container löschen +pct destroy + +# Credentials-Datei löschen (optional) +rm credentials/sb-.json +``` + +## 📈 Performance + +### Wie viele Dokumente kann das System verarbeiten? + +Abhängig von: +- RAM (mehr RAM = mehr Dokumente) +- Disk-Performance (SSD empfohlen) +- pgvector-Index-Konfiguration + +Typisch: 10.000 - 100.000 Dokumente + +### Wie optimiere ich die Performance? + +1. **Mehr RAM:** `pct set --memory 8192` +2. **SSD-Storage:** ZFS mit SSD +3. **Index-Tuning:** IVFFlat-Parameter anpassen +4. **Connection-Pooling:** PostgREST-Konfiguration + +### Wie skaliere ich das System? + +- **Vertikal:** Mehr CPU/RAM für Container +- **Horizontal:** Mehrere Container mit Load-Balancer +- **Datenbank:** PostgreSQL-Replikation + +## 🔒 Sicherheit + +### Ist das System sicher? + +Ja, mit mehreren Sicherheitsebenen: +- Unprivileged LXC-Container +- Docker-Isolation +- JWT-basierte API-Authentifizierung +- Credentials nicht im Git + +### Sollte ich HTTPS verwenden? + +Ja, für Produktiv-Systeme: +1. NGINX Reverse Proxy einrichten +2. Let's Encrypt SSL-Zertifikat +3. HTTPS-Only-Modus + +### Wie ändere ich Passwörter? + +```bash +# n8n-Passwort +./update_credentials.sh --ctid --n8n-password "NewPass123" + +# PostgreSQL-Passwort (manuell in .env ändern) +pct exec -- nano /opt/customer-stack/.env +pct exec -- docker compose -f /opt/customer-stack/docker-compose.yml restart +``` + +## 📚 Weitere Hilfe + +### Wo finde ich mehr Dokumentation? + +- [Installation](Installation.md) +- [Credentials-Management](Credentials-Management.md) +- [Testing](Testing.md) +- [Architecture](Architecture.md) +- [Troubleshooting](Troubleshooting.md) + +### Wie kann ich zum Projekt beitragen? + +1. Fork das Repository +2. Erstellen Sie einen Feature-Branch +3. Implementieren Sie Ihre Änderungen +4. Erstellen Sie einen Pull Request + +### Wo melde ich Bugs? + +Erstellen Sie ein Issue im Repository mit: +- Fehlerbeschreibung +- Reproduktionsschritte +- Log-Dateien +- System-Informationen + +--- + +**Haben Sie weitere Fragen?** +Erstellen Sie ein Issue oder konsultieren Sie die [Troubleshooting](Troubleshooting.md)-Seite.