customer-installer/CREDENTIALS_MANAGEMENT.md

# Credentials Management System

Dieses System ermöglicht die zentrale Verwaltung und Aktualisierung von Credentials für installierte LXC-Container.

## Übersicht

Das Credentials-Management-System besteht aus drei Komponenten:

1. **Automatisches Speichern** - Credentials werden bei der Installation automatisch gespeichert
2. **Manuelles Speichern** - Credentials können aus JSON-Output extrahiert werden
3. **Update-System** - Credentials können zentral aktualisiert werden

---

## 1. Automatisches Speichern bei Installation

Bei jeder Installation wird automatisch eine Credentials-Datei erstellt:

```bash
# Installation durchführen
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90

# Credentials werden automatisch gespeichert in:
# credentials/<hostname>.json
```

**Beispiel:** `credentials/sb-1769276659.json`

---

## 2. Manuelles Speichern von Credentials

Falls Sie Credentials aus dem JSON-Output extrahieren möchten:

### Aus JSON-String
```bash
./save_credentials.sh --json '{"ctid":769276659,"hostname":"sb-1769276659",...}'
```

### Aus JSON-Datei
```bash
./save_credentials.sh --json-file /tmp/install_output.json
```

### Mit benutzerdefiniertem Ausgabepfad
```bash
./save_credentials.sh --json-file output.json --output my-credentials.json
```

### Mit formatierter Ausgabe
```bash
./save_credentials.sh --json-file output.json --format
```

---

## 3. Credentials aktualisieren

### Ollama-URL aktualisieren (z.B. von IP zu Hostname)

```bash
# Von IP zu Hostname wechseln
./update_credentials.sh --ctid 769276659 --ollama-url http://ollama.local:11434
```

### Ollama-Modell ändern

```bash
# Anderes Chat-Modell verwenden
./update_credentials.sh --ctid 769276659 --ollama-model llama3.2:3b

# Anderes Embedding-Modell verwenden
./update_credentials.sh --ctid 769276659 --embedding-model nomic-embed-text:v1.5
```

### Mehrere Credentials gleichzeitig aktualisieren

```bash
./update_credentials.sh --ctid 769276659 \
  --ollama-url http://ollama.local:11434 \
  --ollama-model llama3.2:3b \
  --embedding-model nomic-embed-text:v1.5
```

### Aus Credentials-Datei aktualisieren

```bash
# 1. Credentials-Datei bearbeiten
nano credentials/sb-1769276659.json

# 2. Änderungen anwenden
./update_credentials.sh --ctid 769276659 --credentials-file credentials/sb-1769276659.json
```

---

## Credentials-Datei Struktur

```json
{
  "container": {
    "ctid": 769276659,
    "hostname": "sb-1769276659",
    "fqdn": "sb-1769276659.userman.de",
    "ip": "192.168.45.45",
    "vlan": 90
  },
  "urls": {
    "n8n_internal": "http://192.168.45.45:5678/",
    "n8n_external": "https://sb-1769276659.userman.de",
    "postgrest": "http://192.168.45.45:3000",
    "chat_webhook": "https://sb-1769276659.userman.de/webhook/rag-chat-webhook/chat",
    "upload_form": "https://sb-1769276659.userman.de/form/rag-upload-form"
  },
  "postgres": {
    "host": "postgres",
    "port": 5432,
    "db": "customer",
    "user": "customer",
    "password": "HUmMLP8NbW2onmf2A1"
  },
  "supabase": {
    "url": "http://postgrest:3000",
    "url_external": "http://192.168.45.45:3000",
    "anon_key": "eyJhbGci...",
    "service_role_key": "eyJhbGci...",
    "jwt_secret": "IM9/HRQR..."
  },
  "ollama": {
    "url": "http://192.168.45.3:11434",
    "model": "ministral-3:3b",
    "embedding_model": "nomic-embed-text:latest"
  },
  "n8n": {
    "encryption_key": "d0c9c0ba...",
    "owner_email": "admin@userman.de",
    "owner_password": "FAmeVE7t9d1iMIXWA1",
    "secure_cookie": false
  },
  "log_file": "/root/customer-installer/logs/sb-1769276659.log",
  "created_at": "2026-01-24T18:00:00+01:00",
  "updateable_fields": {
    "ollama_url": "Can be updated to use hostname instead of IP",
    "ollama_model": "Can be changed to different model",
    "embedding_model": "Can be changed to different embedding model",
    "postgres_password": "Can be updated (requires container restart)",
    "n8n_owner_password": "Can be updated (requires container restart)"
  }
}
```

---

## Updatebare Felder

### Sofort wirksam (kein Neustart erforderlich)

| Feld | Beschreibung | Beispiel |
|------|--------------|----------|
| `ollama.url` | Ollama Server URL | `http://ollama.local:11434` |
| `ollama.model` | Chat-Modell | `llama3.2:3b`, `ministral-3:3b` |
| `ollama.embedding_model` | Embedding-Modell | `nomic-embed-text:v1.5` |

**Diese Änderungen werden sofort in n8n übernommen!**

### Neustart erforderlich

| Feld | Beschreibung | Neustart-Befehl |
|------|--------------|-----------------|
| `postgres.password` | PostgreSQL Passwort | `pct exec <ctid> -- bash -c 'cd /opt/customer-stack && docker compose restart'` |
| `n8n.owner_password` | n8n Owner Passwort | `pct exec <ctid> -- bash -c 'cd /opt/customer-stack && docker compose restart'` |

---

## Workflow: Von IP zu Hostname wechseln

### Szenario
Sie möchten den Ollama-Server per Hostname statt IP ansprechen.

### Schritte

1. **DNS/Hostname einrichten**
   ```bash
   # Sicherstellen, dass ollama.local auflösbar ist
   ping ollama.local
   ```

2. **Credentials-Datei bearbeiten** (optional)
   ```bash
   nano credentials/sb-1769276659.json
   ```
   
   Ändern Sie:
   ```json
   "ollama": {
     "url": "http://ollama.local:11434",
     ...
   }
   ```

3. **Update durchführen**
   ```bash
   # Direkt per CLI
   ./update_credentials.sh --ctid 769276659 --ollama-url http://ollama.local:11434
   
   # ODER aus Datei
   ./update_credentials.sh --ctid 769276659 --credentials-file credentials/sb-1769276659.json
   ```

4. **Verifizieren**
   ```bash
   # In n8n einloggen und Ollama-Credential prüfen
   # Oder Workflow testen
   ```

**Fertig!** Die Änderung ist sofort wirksam, kein Container-Neustart erforderlich.

---

## Sicherheit

### Credentials-Dateien schützen

```bash
# Verzeichnis-Berechtigungen setzen
chmod 700 credentials/

# Datei-Berechtigungen setzen
chmod 600 credentials/*.json

# Nur root kann lesen
chown root:root credentials/*.json
```

### Credentials aus Git ausschließen

Die `.gitignore` sollte enthalten:
```
credentials/*.json
!credentials/example-credentials.json
logs/*.log
```

---

## Backup

### Credentials sichern

```bash
# Alle Credentials sichern
tar -czf credentials-backup-$(date +%Y%m%d).tar.gz credentials/

# Verschlüsselt sichern
tar -czf - credentials/ | gpg -c > credentials-backup-$(date +%Y%m%d).tar.gz.gpg
```

### Credentials wiederherstellen

```bash
# Aus Backup wiederherstellen
tar -xzf credentials-backup-20260124.tar.gz

# Aus verschlüsseltem Backup
gpg -d credentials-backup-20260124.tar.gz.gpg | tar -xz
```

---

## Troubleshooting

### Credential-Update schlägt fehl

```bash
# n8n-Logs prüfen
pct exec 769276659 -- docker logs n8n

# n8n neu starten
pct exec 769276659 -- bash -c 'cd /opt/customer-stack && docker compose restart n8n'

# Update erneut versuchen
./update_credentials.sh --ctid 769276659 --ollama-url http://ollama.local:11434
```

### Credentials-Datei beschädigt

```bash
# JSON validieren
python3 -m json.tool credentials/sb-1769276659.json

# Aus Installation-JSON neu erstellen
./save_credentials.sh --json-file logs/sb-1769276659.log
```

### Ollama nicht erreichbar

```bash
# Von Container aus testen
pct exec 769276659 -- curl http://ollama.local:11434/api/tags

# DNS-Auflösung prüfen
pct exec 769276659 -- nslookup ollama.local

# Netzwerk-Konnektivität prüfen
pct exec 769276659 -- ping -c 3 ollama.local
```

---

## Best Practices

1. **Immer Credentials-Datei erstellen**
   - Nach jeder Installation automatisch erstellt
   - Manuell mit `save_credentials.sh` wenn nötig

2. **Credentials-Dateien versionieren**
   - Änderungen dokumentieren
   - Datum im Dateinamen: `sb-1769276659-20260124.json`

3. **Regelmäßige Backups**
   - Credentials-Verzeichnis täglich sichern
   - Verschlüsselt aufbewahren

4. **Hostname statt IP verwenden**
   - Flexibler bei Infrastruktur-Änderungen
   - Einfacher zu merken und zu verwalten

5. **Updates testen**
   - Erst in Test-Umgebung
   - Dann in Produktion

---

## Beispiel-Workflow

### Komplettes Beispiel: Neue Installation mit Credentials-Management

```bash
# 1. Installation durchführen
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90 > install_output.json

# 2. Credentials automatisch gespeichert in credentials/sb-<timestamp>.json

# 3. Credentials anzeigen
cat credentials/sb-1769276659.json | python3 -m json.tool

# 4. Später: Ollama auf Hostname umstellen
./update_credentials.sh --ctid 769276659 --ollama-url http://ollama.local:11434

# 5. Verifizieren
pct exec 769276659 -- docker exec n8n curl http://ollama.local:11434/api/tags

# 6. Backup erstellen
tar -czf credentials-backup-$(date +%Y%m%d).tar.gz credentials/
```

---

## Zusammenfassung

✅ **Credentials werden automatisch gespeichert**  
✅ **Zentrale Verwaltung in JSON-Dateien**  
✅ **Einfaches Update-System**  
✅ **Sofortige Wirkung für Ollama-Änderungen**  
✅ **Keine Container-Neustarts für Ollama-Updates**  
✅ **Versionierung und Backup möglich**

Das System ermöglicht flexible Credential-Verwaltung und macht es einfach, von IP-basierten zu Hostname-basierten Konfigurationen zu wechseln.