deploy-email-plesk-kerio-nextcloud/README.md

deploy-email-plesk-kerio-nextcloud

Tool, um neue Mitarbeiter:innen-Konten in einem Rutsch über drei Systeme auszurollen und am Ende eine PDF mit den Zugangsdaten zu erzeugen:

1. Plesk – Mailpostfach anlegen (nur Mailserver-Login, keine Plesk-GUI).
2. Kerio Connect – Benutzer anlegen + POP3-Sammler einrichten, der die Mails alle paar Minuten vom Plesk-Server abholt (14 Tage auf dem Server belassen, SSL).
3. Nextcloud – Benutzer (Username = vorname.nachname, lowercase, Umlaute transliteriert) mit Gruppe und Speicherquota anlegen.
4. PDF – pro Benutzer eine PDF + eine Sammel-PDF mit allen Zugangsdaten.

CLI und Tkinter-GUI mit „+ Zeile"-Endlosfeldern.

---

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
$EDITOR .env

Tkinter ist Teil der Python-Standardbibliothek, unter Debian/Ubuntu ggf. sudo apt install python3-tk.

Konfiguration (.env)

Plesk-Backend wählen (PLESK_BACKEND)

Dreistufige Wahl, je nachdem welchen Zugriff du auf das Plesk hast:

Backend	Wann?	Was passiert
manual	Shared-Host beim Kunden – kein API, kein SSH (Default)	Tool legt nichts in Plesk an. Im Webinterface manuell anlegen, dann Tool laufen lassen (oder andersrum – Kerio-POP3-Sammler funktioniert erst, wenn das Postfach existiert).
api	Eigener/dedizierter Plesk mit REST-API	Anlegen via /api/v2/cli/mail/call (entspricht plesk bin mail). Auth über PLESK_API_KEY (bevorzugt) oder PLESK_USER / PLESK_PASSWORD.
ssh	Eigener Plesk, API blockiert, aber SSH offen	paramiko öffnet SSH und ruft plesk bin mail direkt. Auth über Key (PLESK_SSH_KEY) oder Passwort (PLESK_SSH_PASSWORD). Bei Bedarf PLESK_SSH_USE_SUDO=true.

SSH-Backend braucht zusätzlich paramiko: pip install paramiko. Für manual reicht das Standard-requirements.txt.

Restliche Variablen

Variable	Beschreibung
KERIO_ADMIN_USER	i.d.R. Admin
KERIO_ADMIN_PASSWORD	Adminpasswort
KERIO_ADMIN_PORT	Standard 4040
NEXTCLOUD_ADMIN_USER	Admin-User (App-Passwort empfohlen)
NEXTCLOUD_ADMIN_PASSWORD	Admin- oder App-Passwort
POP3_PORT	POP3-Sammler in Kerio (default 995 = POP3S)
POP3_SSL	Leer → Auto: 110 ⇒ aus, sonst an. Manuell true/false.
POP3_KEEP_DAYS	Tage, die Mails auf Plesk verbleiben (default 14)
SMTP_PORT	Nur für die PDF-Anzeige (default 465, Mailprogramm-Konfig)
IMAP_PORT	Nur für die Minimal-PDF-Anzeige (default 993 = IMAPS)
VERIFY_TLS	false nur bei Test/selbst signierten Zertifikaten

---

Plesk-API-Key per SSH erzeugen (nur für PLESK_BACKEND=api)

Plesk lässt das Anlegen von API-Keys nicht in der Web-GUI zu. Per SSH auf dem Plesk-Host:

# Login als root oder Plesk-Admin
plesk bin secret_key --create -ip-address 0.0.0.0/0 -description "deploy-tool"
# Ausgabe-Beispiel:
#   API key was successfully generated. Key:
#   1a2b3c4d-1234-5678-9abc-deadbeef0001

Den Key in .env als PLESK_API_KEY=… eintragen. Tipp: -ip-address möglichst auf die IP einschränken, von der das Tool ausgeführt wird (z.B. -ip-address 192.0.2.10).

Vorhandene Keys listen / löschen:

plesk bin secret_key --list
plesk bin secret_key --delete <key>

---

CSV-Format

UTF-8, Trennzeichen ; oder , (wird automatisch erkannt). Kopfzeile case-insensitive. Beispiel: example.csv.

Spalte	Pflicht	Bedeutung
Vorname	ja	Vorname
Name	ja	Nachname
emailadresse	ja	volle Mailadresse, ist Login bei Plesk + Kerio
pleskhost	ja	Hostname Plesk-Mailserver – auch im manual-Modus Pflicht, weil Kerio davon per POP3 abholt
keriohost	ja	Hostname Kerio Connect (Admin-API auf Port 4040, Webmail auf 443)
nextcloudhost	ja	Nextcloud-Hostname
kerioemailkennwort	ja	Passwort für den Kerio-User
pleskemailkennwort	ja	Passwort für das Plesk-Mailpostfach
nextcloudgruppe	nein	Gruppe in Nextcloud (wird angelegt falls nicht vorhanden)
nextcloudspeicher	nein	Speicher in GB. Leer = unlimitiert
nextcloudkennwort	ja	Passwort für den Nextcloud-User

Der Nextcloud-Username wird aus Vor-/Nachname abgeleitet (vorname.nachname, lowercase, ä→ae, ö→oe, ü→ue, ß→ss). Die Emailadresse aus der CSV wird im Nextcloud-Profil als E-Mail eingetragen.

Hostnamen-Eingabe ist tolerant: cloud.foo.de, https://cloud.foo.de und https://cloud.foo.de/ werden alle akzeptiert – Schema (http(s)://) und Trailing-Slash werden automatisch gestrippt, sodass beim URL-Bau kein doppeltes https://https://… entsteht.

---

Aufruf

CLI

Voller Lauf (Plesk + Kerio + Nextcloud + PDFs):

python deploy.py --csv kunden.csv --output ./output

Nur PDFs aus der CSV neu erzeugen, ohne Plesk/Kerio/Nextcloud anzufassen (z.B. wenn die Konten schon angelegt sind oder eine PDF wiederholt ausgedruckt werden soll):

python deploy.py --csv kunden.csv --pdf-only

Weitere Flags:

Flag	Bedeutung
--csv PATH	CSV-Datei einlesen
--output D	Verzeichnis für PDFs + Admin-Report (default ./output)
--pdf-only	Nur PDFs schreiben, keine Account-Anlage
--gui	GUI starten (auch ohne --csv aufrufbar)

Exit-Code 0 wenn alle Konten ohne Fehler verarbeitet wurden, sonst 1.

GUI

python deploy.py --gui
# oder einfach
python deploy.py

Das Fenster startet maximiert. Jeder Account ist eine Karte mit zwei Zeilen: oben die Person (Vorname, Name, Email) + Lösch-Button, unten drei Service-Gruppen (Plesk / Kerio / Nextcloud) mit Host + Passwort. Passwort- Felder sind per Default maskiert (•); ein 👁-Toggle neben jedem Passwort schaltet temporär auf Klartext (🙈) und wieder zurück. Die Karten sind mit #1, #2, … durchnummeriert, Fehlermeldungen referenzieren diese Nummern.

Buttons in der Toolbar:

Button	Wirkung
+ Zeile	Neue leere Karte am Ende anhängen
CSV laden …	Felder aus einer bestehenden CSV befüllen
CSV speichern …	Aktuell ausgefüllte Karten als CSV exportieren (Round-Trip-fähig)
Ausgabeordner …	Zielverzeichnis für PDFs + Admin-Report wählen
📄 Nur PDF	Nur PDFs schreiben, keine API-Aufrufe
Ausführen ▶	Konten anlegen + PDFs + Admin-Report
✕ löschen (rot)	Karte entfernen (auch die letzte – es bleibt eine leere)

Die per CSV speichern … exportierte Datei enthält Klartext-Passwörter – sicher ablegen / verschlüsselt versenden, und die *.csv ist via .gitignore (Ausnahme example.csv) standardmäßig vom Repo ausgeschlossen.

Log unten im Fenster zeigt Fortschritt; nach dem Lauf öffnet eine Hinweis-Box mit dem Pfad zur Sammel-PDF.

---

Ablauf je Konto

Plesk: Mailpostfach anlegen
       - PLESK_BACKEND=manual → übersprungen (manuell in Plesk-GUI anlegen)
       - PLESK_BACKEND=api/ssh → automatisch via `plesk bin mail`
   ↓
Kerio User: anlegen oder überspringen wenn schon vorhanden.
            Beim Anlegen wird `allowPasswordChange=false` gesetzt
            (User darf sein Passwort nicht selbst ändern).
   ↓
Kerio POP3-Sammler: UPSERT – existierender wird via Delivery.setPop3Account
            mit aktuellen Werten überschrieben, sonst neu via
            Delivery.addPop3AccountList. So werden alte/kaputte Sammler
            automatisch repariert und Passwort-Änderungen aus der CSV
            ziehen sich beim nächsten Lauf von selbst nach.
            (Port aus POP3_PORT=995, SSL Auto-Erkennung,
             14 Tage auf Plesk belassen.)
   ↓
Nextcloud: User vorname.nachname mit Gruppe + Quota anlegen
           (übersprungen wenn vorhanden).
   ↓
PDFs schreiben (Einzel + Sammel, voll + minimal) und Admin-Report.

Am Ende werden pro Lauf folgende Dateien geschrieben (alle in output/, keine Zeitstempel im Namen → erneuter Lauf überschreibt):

Datei	Inhalt
zugangsdaten_<email>.pdf	Voll pro Benutzer: Plesk-Mailpostfach + Kerio + Nextcloud
zugangsdaten_minimal_<email>.pdf	Minimal pro Benutzer: nur Email (Kerio) + Cloud (Nextcloud)
zugangsdaten_gesamt.pdf	Sammel-PDF aller voller Datensätze
zugangsdaten_gesamt_minimal.pdf	Sammel-PDF aller minimalen Datensätze
_admin_report.txt	Status pro Konto (✓/·/⚠/✗) inkl. Zeitstempel im Header. NICHT für den Kunden – Admin-Doku.

Die Minimal-PDF enthält genau das, was der Endkunde fürs Mailprogramm und die Cloud-Anmeldung braucht (Mailadresse, Kennwort, SMTP, IMAP, Cloud-URL, Cloud-Username, Cloud-Kennwort) – ohne Backend-Details wie POP3-Sammler oder Plesk-Mailserver.

Idempotenz – bestehende Konten werden übersprungen oder aktualisiert

Jeder Sub-Schritt wird einzeln geprüft. Im Admin-Report stehen die Schritte separat (z.B. Kerio User und Kerio POP3 als zwei Zeilen):

Sub-Schritt	Prüfung	Wenn vorhanden
Plesk	mail --info (api/ssh) bzw. ohnehin Manual-Modus	übersprungen
Kerio User	Users.get mit loginName + domainId	übersprungen
Kerio POP3	Delivery.getPop3AccountList, Match auf (deliveryAddress, server, userName)	aktualisiert via Delivery.setPop3Account (kein Skip! repariert kaputte Einträge + zieht CSV-Änderungen mit)
Nextcloud	GET /ocs/v2.php/cloud/users/<vorname.nachname>	übersprungen (keine Quota-/Gruppen-Änderung)

→ Eine CSV kann gefahrlos mehrfach laufen. Statuswerte: ✓ angelegt / ✓ aktualisiert / · übersprungen / ⚠ manuell / ✗ Fehler.

Caveats:

• Kerio-User-Prüfung matcht loginName in der zur Mailadresse passenden Domain – Aliase auf einer anderen Domain werden nicht erkannt.
• Nextcloud prüft den abgeleiteten Username vorname.nachname – existiert derselbe Mensch dort unter abweichendem Username, wird das nicht gefunden.
• Kerio-POP3 wird absichtlich aktualisiert statt übersprungen: ohne diese Selbstreparatur bliebe ein einmal kaputt angelegter Sammler dauerhaft defekt. Nebeneffekt: ein in der Kerio-Webadmin manuell verstellter Sammler wird beim nächsten Tool-Lauf wieder auf die CSV-Werte gezogen.

Workflow bei PLESK_BACKEND=manual (Shared Host)

1. CSV vorbereiten / in der GUI eintippen.
2. Tool laufen lassen → Kerio-User + POP3-Sammler + Nextcloud-User werden angelegt, PDFs geschrieben, Admin-Report aufgelistet welche Mailpostfächer manuell anzulegen sind.
3. Im Plesk-Webinterface des Kunden für jeden Eintrag die Mailadresse mit exakt dem in der CSV vergebenen Plesk-Mail-Passwort einrichten.
4. Sobald das Postfach existiert, holt der Kerio-Sammler automatisch eingehende Mails ab.

---

Hinweise / Caveats

• Kerio API-Methoden entsprechen der offiziellen Kerio-Connect-Doku (Delivery.idl + User-Struct, siehe Kerio Admin API Reference). Konkret verwendet: Session.login, Domains.get, Users.get, Users.create, Delivery.getPop3AccountList, Delivery.addPop3AccountList, Delivery.setPop3Account. Pop3Account- Felder: isActive, server, port, mode (NoSsl/SpecialPort/StlsCommand), authentication (PlainPop3/Apop), userName, password, deliveryAddress, leaveOnServer{enabled, removeAfterPeriod{enabled,value}}.
• Plesk REST-CLI-Wrapper: nutzt /api/v2/cli/mail/call (entspricht plesk bin mail). Verfügbar ab Plesk Obsidian.
• Nextcloud OCS: die Admin-Credentials brauchen das Recht „Benutzer verwalten". App-Passwort empfohlen, damit der Account nicht 2FA-geschützt bleibt.
• TLS: VERIFY_TLS=false nur in Testumgebungen. Self-signed Zertifikate gehören in einen lokalen Trust-Store, nicht ignoriert.
• Passwörter stehen sowohl in der CSV als auch in den PDFs im Klartext. CSV nach erfolgreichem Lauf löschen, PDFs verschlüsselt versenden.

Dateien

deploy.py             CLI-Entry + Orchestrierung
gui.py                Tkinter-GUI mit Endlosfeldern
config.py             .env-Loader
models.py             Account / Result Datentypen
pdf.py                ReportLab PDF-Erzeugung (kunden-tauglich)
clients/plesk.py      Plesk REST-CLI-Wrapper      (PLESK_BACKEND=api)
clients/plesk_ssh.py  Plesk SSH-Wrapper, paramiko (PLESK_BACKEND=ssh)
clients/kerio.py      Kerio JSON-RPC Admin-Client
clients/nextcloud.py  Nextcloud OCS-Client
example.csv           Beispiel-Eingabedatei
.env.example          Beispiel-Konfiguration