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.

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

# Format: 7XXXXXXXXX (10 Stellen)
# Beispiel: 769276659

Kann ich eine eigene CTID angeben?

Ja, mit dem --ctid Parameter:

./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:

./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?

./install.sh \
  --storage local-zfs \
  --bridge vmbr0 \
  --ip 192.168.45.100/24 \
  --vlan 90

Kann ich VLAN deaktivieren?

Ja, setzen Sie --vlan 0:

./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:

./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?

pct exec <ctid> -- docker exec n8n \
  n8n user-management:reset \
  --email=admin@userman.de \
  --password=NewPassword123

🐳 Docker & Container

Welche Docker-Container werden erstellt?

customer-postgres - PostgreSQL 16 mit pgvector
customer-postgrest - PostgREST API
n8n - Workflow-Automation

Wie kann ich in einen Container einloggen?

# 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?

# 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?

# 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?

# 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:

Tabelle neu erstellen
Anderes Embedding-Modell verwenden
Alle Dokumente neu embedden

-- 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?

Via n8n Web-Interface: http://<ip>:5678
Login mit Credentials aus credentials/sb-*.json
Workflow bearbeiten und speichern

Wird der Workflow bei Neustart geladen?

Ja, automatisch via n8n-workflow-reload.service

Wie kann ich eigene Workflows importieren?

# 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?

n8n API - http://<ip>:5678/rest/*
PostgREST API - http://<ip>:3000/*
Chat-Webhook - http://<ip>:5678/webhook/rag-chat-webhook/chat
Upload-Form - http://<ip>:5678/form/rag-upload-form

Wie authentifiziere ich mich bei der API?

n8n API:

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

PostgREST API:

# 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:

NGINX Reverse Proxy einrichten
SSL-Zertifikat konfigurieren
Firewall-Regeln anpassen

Wie teste ich die Chat-API?

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:

# 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?

./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?

./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?

Test-Output analysieren
Troubleshooting konsultieren
Logs prüfen
Bei Bedarf Issue erstellen

🔄 Updates & Wartung

Wie aktualisiere ich das System?

# 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?

# 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?

# 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?

# 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?

Mehr RAM: pct set <ctid> --memory 8192
SSD-Storage: ZFS mit SSD
Index-Tuning: IVFFlat-Parameter anpassen
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:

NGINX Reverse Proxy einrichten
Let's Encrypt SSL-Zertifikat
HTTPS-Only-Modus

Wie ändere ich Passwörter?

# 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?

Wie kann ich zum Projekt beitragen?

Fork das Repository
Erstellen Sie einen Feature-Branch
Implementieren Sie Ihre Änderungen
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-Seite.