# KeyHelp Manager - Detaillierte Installationsanleitung

Diese Anleitung führt Sie Schritt für Schritt durch die Installation und Konfiguration des KeyHelp Manager WHMCS-Moduls.

## 📋 Voraussetzungen prüfen

Bevor Sie mit der Installation beginnen, stellen Sie sicher, dass folgende Anforderungen erfüllt sind:

### WHMCS-System

- [ ] WHMCS Version 8.13 oder höher installiert
- [ ] PHP Version 8.3 oder höher
- [ ] Guzzle HTTP Client verfügbar (normalerweise in WHMCS integriert)
- [ ] MySQL/MariaDB Datenbank
- [ ] SSL-Zertifikat für WHMCS (empfohlen)
- [ ] Admin-Zugriff auf WHMCS

### KeyHelp-Server

- [ ] KeyHelp installiert und erreichbar
- [ ] KeyHelp API v2 aktiviert
- [ ] Admin-Zugang zu KeyHelp
- [ ] SSL-Zertifikat für KeyHelp (empfohlen)
- [ ] Firewall-Regeln erlauben Zugriff von WHMCS-Server

### Netzwerk

- [ ] WHMCS-Server kann KeyHelp-Server über HTTP/HTTPS erreichen
- [ ] Port 80/443 ist offen (je nach Konfiguration)
- [ ] DNS-Auflösung funktioniert korrekt

## 🚀 Schritt 1: KeyHelp API vorbereiten

### 1.1 API-Key in KeyHelp erstellen

1. Loggen Sie sich als Administrator in Ihr KeyHelp-Panel ein:
   ```
   https://ihr-keyhelp-server.de
   ```

2. Navigieren Sie zu **Einstellungen** (Zahnrad-Symbol oben rechts)

3. Klicken Sie auf **API** im linken Menü

4. Klicken Sie auf **Neuen API-Schlüssel erstellen**

5. Konfigurieren Sie den API-Key:
   - **Name:** `WHMCS Provisioning`
   - **Berechtigungen:** Wählen Sie **Administrator** oder erteilen Sie folgende spezifische Rechte:
     - Benutzer erstellen/bearbeiten/löschen
     - Domains erstellen/bearbeiten/löschen
     - Statistiken abrufen
     - Sessions erstellen
   - **IP-Whitelist:** (Optional aber empfohlen) Tragen Sie die IP-Adresse Ihres WHMCS-Servers ein

6. Klicken Sie auf **Erstellen**

7. **WICHTIG:** Kopieren Sie den generierten API-Key sofort und speichern Sie ihn sicher!
   ```
   Beispiel: kh_live_1234567890abcdefghijklmnopqrstuvwxyz
   ```
   
   ⚠️ **Der Key wird nur einmal angezeigt!**

### 1.2 API testen (Optional)

Testen Sie den API-Zugriff vom WHMCS-Server aus:

```bash
# Mit SSL (empfohlen)
curl -X GET "https://ihr-keyhelp-server.de/api/v2/server/version" \
  -H "X-API-Key: IHR_API_KEY" \
  -H "Accept: application/json"

# Ohne SSL (nur für Tests)
curl -X GET "http://ihr-keyhelp-server.de/api/v2/server/version" \
  -H "X-API-Key: IHR_API_KEY" \
  -H "Accept: application/json"
```

Erwartete Antwort:
```json
{
  "version": "24.1.0",
  "api_version": "2.0"
}
```

## 🔧 Schritt 2: Modul-Dateien installieren

### 2.1 Dateien hochladen

#### Option A: Via FTP/SFTP

1. Verbinden Sie sich mit Ihrem WHMCS-Server via FTP/SFTP

2. Navigieren Sie zum WHMCS-Installationsverzeichnis:
   ```
   /var/www/whmcs/
   ```

3. Laden Sie das komplette `keyhelpmanager`-Verzeichnis in folgenden Pfad hoch:
   ```
   /var/www/whmcs/modules/servers/keyhelpmanager/
   ```

4. Stellen Sie sicher, dass folgende Struktur existiert:
   ```
   modules/
   └── servers/
       └── keyhelpmanager/
           ├── keyhelpmanager.php
           └── templates/
               └── clientarea.tpl
   ```

#### Option B: Via SSH

```bash
# Zum WHMCS-Verzeichnis navigieren
cd /var/www/whmcs/modules/servers/

# Repository klonen (falls Git verwendet wird)
git clone https://github.com/ihr-repo/keyhelpmanager.git

# Oder Dateien aus ZIP extrahieren
unzip keyhelpmanager.zip

# Dateien verschieben falls nötig
mv keyhelpmanager-main keyhelpmanager
```

### 2.2 Dateirechte setzen

Setzen Sie die korrekten Berechtigungen:

```bash
# Zum Modul-Verzeichnis
cd /var/www/whmcs/modules/servers/keyhelpmanager/

# Dateien: 644 (rw-r--r--)
find . -type f -exec chmod 644 {} \;

# Verzeichnisse: 755 (rwxr-xr-x)
find . -type d -exec chmod 755 {} \;

# Owner setzen (Apache/Nginx User)
chown -R www-data:www-data .

# Oder für andere Systeme
chown -R apache:apache .
chown -R nginx:nginx .
```

### 2.3 Installation verifizieren

Prüfen Sie, ob die Dateien korrekt hochgeladen wurden:

```bash
ls -la /var/www/whmcs/modules/servers/keyhelpmanager/
```

Erwartete Ausgabe:
```
drwxr-xr-x 3 www-data www-data 4096 Jan 15 10:00 .
drwxr-xr-x 8 www-data www-data 4096 Jan 15 09:55 ..
-rw-r--r-- 1 www-data www-data xxxxx Jan 15 10:00 keyhelpmanager.php
drwxr-xr-x 2 www-data www-data 4096 Jan 15 10:00 templates
```

## ⚙️ Schritt 3: Server in WHMCS konfigurieren

### 3.1 Server hinzufügen

1. Loggen Sie sich in den **WHMCS Admin-Bereich** ein:
   ```
   https://ihr-whmcs.de/admin/
   ```

2. Navigieren Sie zu:
   ```
   Setup → Products/Services → Servers
   ```

3. Klicken Sie auf **Add New Server**

### 3.2 Server-Details eintragen

Füllen Sie das Formular aus:

#### Tab: Details

| Feld | Wert | Beschreibung |
|------|------|--------------|
| **Name** | `KeyHelp Server 1` | Interner Name (frei wählbar) |
| **Hostname** | `keyhelp.ihredomain.de` | Hostname ODER IP-Adresse **OHNE** `http://` oder `https://` |
| **IP Address** | `123.45.67.89` | IP-Adresse (optional, falls Hostname verwendet wird) |
| **Type** | `KeyHelp Manager` | Wählen Sie aus dem Dropdown |
| **Username** | _(leer lassen)_ | Nicht benötigt |
| **Password** | `kh_live_123...` | **IHR KEYHELP API-KEY** |
| **Accesshash** | _(leer lassen)_ | Nicht benötigt |

#### Checkboxes

- ✅ **Active** - Server ist aktiv
- ✅ **Secure** - Verwenden Sie SSL (HTTPS) für die Verbindung
- ⬜ **Disable Accounts Automatically** - (optional)

#### Tab: Module Settings

Wenn verfügbar, konfigurieren Sie hier:

| Option | Empfohlener Wert | Beschreibung |
|--------|------------------|--------------|
| **Use SSL** | ✅ On | SSL für API-Verbindung verwenden |
| **Verify SSL Certificate** | ✅ On | SSL-Zertifikat prüfen (bei selbstsigniert: Off) |

### 3.3 Verbindung testen

1. Klicken Sie auf **Test Connection**

2. Erwartete Meldung:
   ```
   ✅ Verbindung erfolgreich! KeyHelp Version: 24.1.0
   ```

3. Bei Fehlermeldungen siehe [Fehlerbehebung](#fehlerbehebung)

4. Klicken Sie auf **Save Changes**

## 📦 Schritt 4: Produkt/Service erstellen

### 4.1 Neues Produkt anlegen

1. Navigieren Sie zu:
   ```
   Setup → Products/Services → Products/Services
   ```

2. Klicken Sie auf **Create a New Group** (falls noch keine Gruppe existiert):
   - **Name:** `Webhosting`
   - **Description:** `KeyHelp Webhosting Pakete`

3. Klicken Sie auf **Create a New Product**

### 4.2 Produkt-Details

#### Tab: Details

| Feld | Beispielwert |
|------|--------------|
| **Product Type** | `Hosting Account` |
| **Product Group** | `Webhosting` |
| **Product Name** | `Basic Webhosting` |
| **Description** | Beschreibung des Pakets |
| **Welcome Email** | `Hosting Account Welcome Email` |

#### Tab: Pricing

Konfigurieren Sie Ihre Preise:

- **Currency:** EUR
- **Payment Type:** Recurring
- **Monthly:** 5.00 EUR
- **Quarterly:** 13.50 EUR
- **Semi-Annually:** 27.00 EUR
- **Annually:** 50.00 EUR

#### Tab: Module Settings

**WICHTIG:** Dies ist der entscheidende Teil!

| Feld | Wert | Beschreibung |
|------|------|--------------|
| **Module Name** | `KeyHelp Manager` | Wählen Sie aus dem Dropdown |
| **Server Group** | `Default` | Oder wählen Sie Ihre Server-Gruppe |
| **Username** | `Domain` | Automatisch aus Domain generieren |
| **Password** | `Generate` | Automatisch generieren |

**Konfigurationsoptionen:**

1. **Hostname (IP or FQDN)**
   - Type: Dropdown
   - Options: Wählen Sie Ihren KeyHelp-Server

2. **API Key**
   - Wird automatisch vom Server übernommen

3. **Use SSL**
   - Default: On

**Aktivierte Funktionen:** (Checkboxes)

- ✅ Create Account
- ✅ Suspend Account
- ✅ Unsuspend Account
- ✅ Terminate Account
- ✅ Change Password
- ✅ Login Link (Single Sign-On)

### 4.3 Konfigurierbare Optionen (Optional)

#### KeyHelp-Pläne als Dropdown

1. Navigieren Sie zu:
   ```
   Setup → Products/Services → Configurable Options
   ```

2. Klicken Sie auf **Create a New Group**:
   - **Group Name:** `KeyHelp Optionen`

3. Klicken Sie auf **Add New Configurable Option**:
   - **Option Name:** `KeyHelp Plan`
   - **Option Type:** `Dropdown`
   - **Options:**
     ```
     Basic|basic
     Professional|professional
     Enterprise|enterprise
     ```

4. Verknüpfen Sie die Gruppe mit Ihrem Produkt:
   - Products/Services → Ihr Produkt → Configurable Options
   - Wählen Sie `KeyHelp Optionen`

### 4.4 Custom Fields anlegen (Optional aber empfohlen)

Diese Felder werden zwar automatisch erstellt, können aber manuell vorbereitet werden:

1. Navigieren Sie zu:
   ```
   Setup → Custom Fields
   ```

2. Wählen Sie **Products/Services** und Ihr Produkt

3. Klicken Sie auf **Add New Custom Field**:

   - **Field Name:** `KeyHelp User ID`
   - **Field Type:** `Text Box`
   - **Description:** `Interne KeyHelp Benutzer-ID`
   - ✅ **Admin Only**
   - Sortierung: `1`

## ✅ Schritt 5: Testen der Installation

### 5.1 Test-Bestellung durchführen

1. Öffnen Sie Ihr WHMCS Frontend als Kunde (im Inkognito-Modus):
   ```
   https://ihr-whmcs.de/
   ```

2. Navigieren Sie zu **Order → Hosting**

3. Wählen Sie Ihr neues Produkt

4. Geben Sie eine Test-Domain ein:
   ```
   test123.de
   ```

5. Schließen Sie die Bestellung ab (nutzen Sie ein Test-Gateway oder manuelle Zahlung)

### 5.2 Account-Erstellung prüfen

1. Als Admin: Navigieren Sie zu **Clients → View/Search Clients**

2. Öffnen Sie den Test-Kunden

3. Klicken Sie auf das neue Service/Produkt

4. Im Tab **Information** sollten Sie sehen:
   - ✅ Username: automatisch generiert
   - ✅ Password: automatisch generiert
   - ✅ Status: Active

5. Prüfen Sie die **Module Commands**:
   - Buttons sollten verfügbar sein: Suspend, Unsuspend, Terminate, Change Password

### 5.3 Client Area testen

1. Loggen Sie sich als Test-Kunde ein

2. Navigieren Sie zu **Services → My Services**

3. Klicken Sie auf das neue Hosting-Paket

4. Sie sollten sehen:
   - ✅ KeyHelp Login-URL (klickbar)
   - ✅ Benutzername (mit Copy-Button)
   - ✅ Passwort (mit Show/Hide und Copy-Button)
   - ✅ Domain-Name
   - ✅ Statistiken (wenn Account erstellt wurde):
     - Speicherplatz-Fortschrittsbalken
     - Traffic-Fortschrittsbalken
     - Anzahl Domains/Datenbanken/E-Mail-Konten

### 5.4 In KeyHelp prüfen

1. Loggen Sie sich in Ihr KeyHelp-Panel ein

2. Navigieren Sie zu **Benutzer**

3. Sie sollten den neu erstellten Benutzer sehen:
   - Username wie in WHMCS
   - Domain zugewiesen
   - Status: Aktiv

### 5.5 Single Sign-On testen

1. Als Admin in WHMCS: Öffnen Sie das Test-Service

2. Klicken Sie auf **Login to KeyHelp** (oder ähnlicher Button)

3. Sie sollten automatisch in KeyHelp eingeloggt werden:
   - Als der jeweilige Benutzer
   - Ohne Passwort-Eingabe

## 🔧 Schritt 6: Produktiv-Konfiguration

### 6.1 Mehrere Server einrichten

Falls Sie mehrere KeyHelp-Server haben:

1. Wiederholen Sie Schritt 3 für jeden Server

2. Erstellen Sie eine **Server Group**:
   ```
   Setup → Products/Services → Servers → Server Groups
   ```

3. Fügen Sie alle KeyHelp-Server zur Gruppe hinzu

4. Konfigurieren Sie Ihre Produkte, um die Server-Gruppe zu nutzen:
   - Automatische Lastverteilung
   - Failover-Funktion

### 6.2 Automatisierung einrichten

#### A) Automatische Provisioning

In WHMCS: **Setup → Automation Settings**

- ✅ Enable Automatic Provisioning
- ✅ Process After: Payment Cleared
- Stellen Sie sicher, dass Cron-Jobs aktiv sind

#### B) Automatische Sperrung

- ✅ Enable Automatic Suspension
- Days Past Due Before Suspension: `7`

#### C) Automatische Kündigung

- ✅ Enable Automatic Termination
- Days Past Due Before Termination: `30`

### 6.3 E-Mail-Templates anpassen

Passen Sie die E-Mail-Templates an:

1. **Setup → Email Templates**

2. Suchen Sie nach:
   - `Hosting Account Welcome Email`

3. Fügen Sie KeyHelp-spezifische Variablen hinzu:
   ```
   KeyHelp Login: https://{$service_server_hostname}
   Benutzername: {$service_username}
   Passwort: {$service_password}
   Domain: {$service_domain}
   ```

### 6.4 Sicherheit härten

1. **IP-Whitelist in KeyHelp**:
   - Beschränken Sie API-Zugriff auf WHMCS-Server-IP

2. **WHMCS Admin-IP-Whitelist**:
   ```
   Setup → General Settings → Security
   ```
   - Tragen Sie erlaubte Admin-IPs ein

3. **Zwei-Faktor-Authentifizierung**:
   - Aktivieren Sie 2FA für alle Admin-Accounts (WHMCS und KeyHelp)

4. **SSL-Zertifikate**:
   - Verwenden Sie gültige SSL-Zertifikate
   - Keine selbstsignierten Zertifikate in Produktion

## 🐛 Fehlerbehebung

### Problem: "Module Not Found"

**Ursache:** Dateien nicht korrekt hochgeladen

**Lösung:**
```bash
# Prüfen Sie den Pfad
ls -la /var/www/whmcs/modules/servers/keyhelpmanager/keyhelpmanager.php

# Wenn nicht gefunden, Dateien neu hochladen
```

### Problem: "Connection Failed"

**Ursachen & Lösungen:**

1. **Firewall blockiert**:
   ```bash
   # Auf WHMCS-Server testen
   telnet keyhelp-server.de 443
   ```

2. **Falscher Hostname**:
   - Verwenden Sie FQDN ODER IP
   - OHNE `http://` oder `https://`

3. **SSL-Problem**:
   - Bei selbstsigniertem Zertifikat: "Verify SSL" deaktivieren

4. **API-Key falsch**:
   - Generieren Sie einen neuen Key in KeyHelp
   - Kopieren Sie ihn exakt (keine Leerzeichen!)

### Problem: "Account Creation Failed"

**Debug-Schritte:**

1. Prüfen Sie Module Log:
   ```
   Utilities → Logs → Module Log
   Filter: keyhelpmanager
   ```

2. Prüfen Sie die API-Response in den Logs

3. Häufige Ursachen:
   - Domain existiert bereits
   - Ungültiger Username
   - Unzureichende API-Berechtigungen
   - KeyHelp-Lizenz-Limit erreicht

### Problem: "Statistics Not Showing"

**Ursache:** API-Endpunkt nicht erreichbar oder User-ID fehlt

**Lösung:**
```bash
# API manuell testen
curl -X GET "https://keyhelp-server.de/api/v2/users/123/statistics" \
  -H "X-API-Key: IHR_KEY"
```

Prüfen Sie, ob `KeyHelp User ID` Custom Field existiert und gefüllt ist.

## 📊 Monitoring

### 6.5 Logging aktivieren

In WHMCS:
```
Setup → General Settings → Other
```
- ✅ Enable Module Debug Logging

Logs finden Sie unter:
```
Utilities → Logs → Module Log
```

### 6.6 Gesundheits-Check einrichten

Erstellen Sie ein Cron-Script für regelmäßige API-Tests:

```bash
#!/bin/bash
# /root/keyhelp-health-check.sh

KEYHELP_HOST="keyhelp.ihredomain.de"
API_KEY="ihr_api_key"

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
  "https://${KEYHELP_HOST}/api/v2/server/version" \
  -H "X-API-Key: ${API_KEY}")

if [ "$RESPONSE" != "200" ]; then
  echo "KeyHelp API nicht erreichbar! HTTP Status: $RESPONSE"
  # Optional: Benachrichtigung senden
  echo "KeyHelp API Down" | mail -s "ALERT: KeyHelp" admin@ihredomain.de
fi
```

Cron-Job:
```bash
# Alle 15 Minuten prüfen
*/15 * * * * /root/keyhelp-health-check.sh
```

## ✨ Fertig!

Herzlichen Glückwunsch! Ihr KeyHelp Manager WHMCS-Modul ist jetzt vollständig installiert und konfiguriert.

### Nächste Schritte

- [ ] Produktiv-Server konfigurieren
- [ ] Mehrere Hosting-Pakete anlegen
- [ ] Preise festlegen
- [ ] Marketing-Material vorbereiten
- [ ] Support-Team schulen

### Wichtige Hinweise

- 🔒 **Sicherheit:** Ändern Sie Ihre API-Keys regelmäßig
- 📝 **Backups:** Sichern Sie regelmäßig WHMCS und KeyHelp
- 🔄 **Updates:** Halten Sie alle Systeme aktuell
- 📞 **Support:** Dokumentieren Sie Ihre Konfiguration für Ihr Team

### Nützliche Links

- KeyHelp Dokumentation: https://www.keyhelp.de/dokumentation
- WHMCS Docs: https://docs.whmcs.com/
- KeyHelp Forum: https://forum.keyhelp.de/

---

**Bei Problemen oder Fragen:** Prüfen Sie die README.md und die Fehlerbehebungssektion. Für weitere Hilfe konsultieren Sie die Community-Foren.