# 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-<timestamp>.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 <ctid> -- 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 <ctid>

# In Docker-Container
pct exec <ctid> -- docker exec -it n8n sh
pct exec <ctid> -- docker exec -it customer-postgres bash
```

### Wie starte ich Container neu?

```bash
# Einzelner Docker-Container
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart n8n

# Alle Docker-Container
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart

# LXC-Container
pct restart <ctid>
```

### Wie stoppe ich Container?

```bash
# Docker-Container stoppen
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml down

# LXC-Container stoppen
pct stop <ctid>
```

## 📊 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 <ctid> -- 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://<ip>: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://<ip>:5678/rest/*`
2. **PostgREST API** - `http://<ip>:3000/*`
3. **Chat-Webhook** - `http://<ip>:5678/webhook/rag-chat-webhook/chat`
4. **Upload-Form** - `http://<ip>:5678/form/rag-upload-form`

### Wie authentifiziere ich mich bei der API?

**n8n API:**
```bash
# Login
curl -X POST http://<ip>:5678/rest/login \
  -H "Content-Type: application/json" \
  -d '{"emailOrLdapLoginId":"admin@userman.de","password":"..."}'
```

**PostgREST API:**
```bash
# Mit API-Key
curl http://<ip>: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://<ip>: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 <ctid> \
  --ollama-model llama2:latest \
  --embedding-model all-minilm:latest
```

### Wie ändere ich die Ollama-URL?

```bash
./update_credentials.sh \
  --ctid <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 <ctid> <ip> <hostname>
```

### 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 <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml pull
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml up -d

# System-Updates
pct exec <ctid> -- apt-get update
pct exec <ctid> -- apt-get upgrade -y
```

### Wie sichere ich Daten?

```bash
# Volumes sichern
pct exec <ctid> -- tar -czf /tmp/backup.tar.gz \
  /opt/customer-stack/volumes/

# Backup herunterladen
pct pull <ctid> /tmp/backup.tar.gz ./backup-$(date +%Y%m%d).tar.gz
```

### Wie stelle ich Daten wieder her?

```bash
# Backup hochladen
pct push <ctid> ./backup-20260124.tar.gz /tmp/backup.tar.gz

# Volumes wiederherstellen
pct exec <ctid> -- tar -xzf /tmp/backup.tar.gz -C /
```

### Wie lösche ich einen Container?

```bash
# Container stoppen
pct stop <ctid>

# Container löschen
pct destroy <ctid>

# Credentials-Datei löschen (optional)
rm credentials/sb-<timestamp>.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 <ctid> --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 <ctid> --n8n-password "NewPass123"

# PostgreSQL-Passwort (manuell in .env ändern)
pct exec <ctid> -- nano /opt/customer-stack/.env
pct exec <ctid> -- 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.