# KeyHelp

ProcessWire direkt aus dem ProcessWire-Adminbereich auf KeyHelp-Domains installieren.

KeyHelp verbindet den ProcessWire-Adminbereich mit [KeyHelp](https://keyhelp.de), einem deutschen Hosting-Control-Panel.

Das Modul ist für ProcessWire-Projekte gedacht, in denen Redakteure oder Administratoren Hosting-Aufgaben direkt im ProcessWire-Backend erledigen sollen: Domains, Kunden, Datenbanken, E-Mail-Konten, FTP-Konten, SSL, PHP-Einstellungen, DNS-Einträge, Cronjobs, Serverstatus und ProcessWire-Installationen.

![KeyHelp Hosting-Verwaltung](assets/keyhelp-hosting-illustration.png)

**Autor:** Maxim Semenov  
**Website:** [smnv.org](https://smnv.org)  
**E-Mail:** [maxim@smnv.org](mailto:maxim@smnv.org)  

Englische Dokumentation: [README.md](README.md)

Wenn dieses Projekt Ihre Arbeit unterstützt, können Sie die weitere Entwicklung fördern: [GitHub Sponsors](https://github.com/sponsors/mxmsmnv) oder [smnv.org/sponsor](https://smnv.org/sponsor/).

## Funktionen

- Dashboard mit Hosting-Status, Ressourcenanzeigen und aktuellen Domains.
- Domains anzeigen, erstellen, öffnen und löschen.
- SSL, Let's Encrypt, HTTPS-Erzwingung, HSTS, PHP-Einstellungen und DNS-Einträge pro Domain verwalten.
- KeyHelp-Kunden anzeigen, erstellen, öffnen und löschen.
- Datenbanken, E-Mail-Konten, FTP-Konten und Cronjobs anzeigen, erstellen und löschen.
- SSL-Zertifikate anzeigen und Ablaufstatus erkennen.
- Serverinformationen anzeigen und Server-Neustart für berechtigte Benutzer auslösen.
- Langsame API-Seiten im Hintergrund laden, damit der ProcessWire-Adminbereich sofort reagiert.
- API-GET-Antworten zwischenspeichern und Cache manuell leeren.
- Debug-Modus mit bereinigten API-Requests, Payloads, Antworten, Cache-Treffern und Laufzeiten.
- Granulare ProcessWire-Berechtigungen.
- Single-Tenant-Modus für einen bestimmten KeyHelp-Kunden.
- Frische ProcessWire-Installationen auf KeyHelp-Domains erstellen.
- Installationsdaten verschlüsselt speichern und auf der Domain-Seite anzeigen.
- ProcessWire-Module aus GitHub-Repositories nach PHP-Syntaxprüfung installieren.

## Voraussetzungen

- ProcessWire 3.0.200+
- PHP 8.0+
- PHP-Erweiterung `curl`
- KeyHelp 19.3+ mit REST-API-Zugriff
- KeyHelp Admin-API-Schlüssel

Das Modul verwendet [KeyHelp API 2.14](https://app.swaggerhub.com/apis-docs/keyhelp/api/2.14) und die `/api/v2` Endpunkte.

## Installation

1. Ordner `KeyHelp` nach `/site/modules/` kopieren.
2. In ProcessWire Admin die Module aktualisieren.
3. Modul `KeyHelp` installieren.
4. KeyHelp-Moduleinstellungen öffnen.
5. KeyHelp-Panel-URL und API-Schlüssel eintragen.
6. Benötigte ProcessWire-Berechtigungen an Rollen vergeben.

## Wichtige Einstellungen

| Einstellung | Standard | Beschreibung |
|---|---:|---|
| Panel URL |  | Basis-URL des KeyHelp-Panels, zum Beispiel `https://panel.example.com`. |
| API Key |  | Admin-API-Schlüssel aus KeyHelp. |
| API Host IP Override |  | Optionaler cURL-DNS-Override für lokale DNS-Probleme. |
| Cache TTL | 60 | Dauer des API-GET-Caches in Sekunden. `0` deaktiviert den Cache. |
| Verify SSL | an | In Produktion aktiviert lassen. Nur für vertrauenswürdige Testpanels mit selbstsignierten Zertifikaten deaktivieren. |
| Interface language | auto | `auto` folgt der ProcessWire-Benutzersprache. `English` oder `Deutsch` erzwingen die Modulsprache. |
| Debug mode | aus | Schreibt bereinigte API-Daten in das ProcessWire-Log `keyhelp-debug`. |
| Document root pattern | `/home/users/{username}/www/{domain}` | Fallback-Pfad für den Installer, wenn die KeyHelp-API kein Document Root liefert. |
| Installer deployment mode | auto | `auto` nutzt lokal bei gleichem Host und SSH bei getrennten Hosts. |
| Installer SSH host | KeyHelp API host | Remote-Host für SSH-Installationen. Platzhalter: `{keyhelp_host}`, `{domain}`, `{username}`. |
| Installer SSH port | 22 | SSH-Port. |
| Installer SSH user | `{username}` | SSH-Benutzer. Standard passt zu typischen KeyHelp-Kundenkonten. |
| Installer SSH private key path |  | Optionaler Private-Key-Pfad auf dem ProcessWire-Server. |
| Installer SSH password |  | Optionales Passwort für Testserver. Für Produktion SSH-Keys verwenden. |
| Installer remote PHP binary | `php` | PHP-Befehl auf dem KeyHelp-Server. |
| Tenant Mode | multi | `single` beschränkt Ansichten und Aktionen auf eine KeyHelp-Kunden-ID. |
| Client ID | 0 | Kunden-ID für Single-Tenant-Modus. |

## Berechtigungen

Superuser haben immer Zugriff. Andere Rollen können folgende Berechtigungen erhalten:

- `keyhelp-view` - Dashboard und Listen anzeigen.
- `keyhelp-edit` - Ressourcen erstellen und bearbeiten.
- `keyhelp-delete` - Ressourcen löschen.
- `keyhelp-server` - Serverinformationen und Neustart im Multi-Tenant-Modus.

## Hintergrundladen

Einige KeyHelp-API-Antworten können mehrere Sekunden dauern. Deshalb rendert das Modul zuerst eine leichte ProcessWire-Seite mit Navigation und Ladeanzeige. Die API-Daten werden danach per Hintergrundrequest geladen und automatisch in die Seite eingesetzt.

Hintergrundladen wird genutzt für Dashboard, Domains, Kunden, Datenbanken, E-Mail, FTP, SSL-Zertifikate, Cronjobs, Serverstatus und Installer-Daten. POST-Aktionen wie Erstellen, Löschen, Speichern und Installieren bleiben synchron, damit Weiterleitungen und Seiteneffekte zuverlässig bleiben.

## ProcessWire Installer

Der Installer kann ProcessWire auf einer ausgewählten KeyHelp-Domain installieren.

Er kann:

- das ProcessWire-Archiv `stable` oder `dev` von GitHub laden;
- eine KeyHelp-Datenbank und einen Datenbankbenutzer erstellen;
- eine zufällige Admin-URL und ein starkes Passwort erzeugen;
- den ProcessWire-CLI-Installer ausführen;
- `.htaccess` für KeyHelp-Apache-Regeln anpassen;
- Admin-URL und Zugangsdaten einmal anzeigen;
- Zugangsdaten verschlüsselt in einer ProcessWire-Datenbanktabelle speichern;
- den Admin-Login einer vorhandenen Installation zurücksetzen;
- ein leeres Zielverzeichnis bereinigen;
- ProcessWire-Module aus GitHub nach `/site/modules` installieren.

Wenn KeyHelp und ProcessWire auf unterschiedlichen Hosts laufen, schaltet `auto` auf SSH-Deployment um. Dabei werden Dateien per SSH hochgeladen, der entfernte PHP-Befehl ausgeführt und die Zeitzone des entfernten Servers verwendet.

## Speicherung der Zugangsdaten

Die vom Installer erzeugten ProcessWire-Zugangsdaten werden in der ProcessWire-Datenbanktabelle `keyhelp_processwire_installs` gespeichert.

Gespeichert werden:

- KeyHelp-Domain-ID und Domainname;
- Installationspfad;
- Admin-URL, Admin-Login und verschlüsseltes Admin-Passwort;
- Datenbank-Host, Port, Name, Benutzer und verschlüsseltes Datenbankpasswort;
- Deployment-Modus, gewählter Branch und Zeitstempel.

Passwörter werden mit AES-256-GCM über OpenSSL verschlüsselt. Der Schlüssel wird aus dem Salt der ProcessWire-Datei `site/config.php` abgeleitet, sodass die gespeicherten Werte nicht ohne diese Site-Konfiguration wiederverwendet werden können.

Die Domainliste zeigt ein `PW`-Badge, wenn gespeicherte Zugangsdaten für eine Domain vorhanden sind. Auf der Domain-Detailseite werden die Zugangsdaten für Benutzer mit der Berechtigung `keyhelp-edit` angezeigt. Wenn eine ProcessWire-Installation auf dem Server erkannt wird, aber noch keine Zugangsdaten gespeichert sind, kann der Installer über "Admin-Login zurücksetzen" neue Zugangsdaten erzeugen und speichern.

## Hinweise

- DNS-Speichern nutzt `PUT` und ersetzt den kompletten Record-Satz. Vor dem Speichern müssen alle DNS-Einträge im JSON enthalten sein.
- Schreibende API-Aktionen leeren den KeyHelp-Cache-Namespace.
- Client-Berechtigungen stellt die KeyHelp-API nicht als eigenen Endpunkt bereit. Das Modul verlinkt deshalb direkt zur passenden KeyHelp-Panel-Seite.
- Die KeyHelp-REST-API bietet keine Start-/Stopp-/Neustart-Endpunkte für einzelne Dienste. Ein Server-Neustart ist über `POST /server/reboot` verfügbar, wenn KeyHelp 26.0+ eingesetzt wird.
- GitHub-Module werden vor dem Kopieren mit `php -l` geprüft. Repositories mit PHP-Syntaxfehlern werden abgelehnt, damit die ProcessWire-Installation nicht beschädigt wird.

## Smoke Tests

Vor einem Release können die nicht-destruktiven Tests ausgeführt werden:

```bash
php tests/smoke.php
php tests/installer-smoke.php
```

`tests/installer-smoke.php` prüft den Installer statisch, ohne Dateien, Datenbanken oder Live-Installationen zu erstellen.

## Dokumentation

Release Notes stehen in [CHANGELOG.md](CHANGELOG.md).

## Lizenz

MIT