Voraussetzungen¶
Diese Seite sagt Ihnen, was auf dem Server vorhanden sein muss, bevor Sie
KCForms installieren. Das gilt für den Betrieb als ROOT.war auf einem
Tomcat, beschrieben unter Installation auf Tomcat.
Zusammengefasst brauchen Sie Java 21, Tomcat 10.1 und eine leere
Datenbank. Einen Datenbank-Treiber müssen Sie im Normalfall nicht
herunterladen, weil KCForms die Treiber mitbringt. Nur in zwei Sonderfällen
legen Sie selbst einen Treiber ab; die stehen
weiter unten.
Server¶
| Was | Version | Bezugsquelle |
|---|---|---|
| Java | 21 (JDK oder JRE) | z. B. Eclipse Temurin: https://adoptium.net/temurin/releases/ |
| Apache Tomcat | 10.1.x | https://tomcat.apache.org/download-10.cgi |
Tomcat 9 und älter passen nicht. KCForms braucht den Jakarta-Namensraum,
den es erst ab Tomcat 10 gibt. Tomcat muss mit Java 21 laufen. Ist auf dem
Server mehr als ein Java installiert, legen Sie das über JAVA_HOME in
setenv.sh bzw. setenv.bat fest.
Arbeitsspeicher: Die mitgelieferte setenv-Vorlage stellt Tomcat 512 MB bis
1 GB zur Verfügung (-Xms512m -Xmx1024m). Passen Sie das an die Zahl der
Anwender und die Größe Ihrer Formulare an.
Das KCForms-Home-Verzeichnis (Standard ~/.kcforms, besser ausdrücklich
über KCFORMS_HOME) muss für den Benutzer, unter dem Tomcat läuft,
beschreibbar sein. Was darin liegt, steht unter
Installation → Das KCForms-Home-Verzeichnis.
Datenbank¶
KCForms braucht eine leere Datenbank und einen Benutzer, der darin Tabellen anlegen darf. Die Tabellen legt KCForms beim ersten Start selbst an. Der Installationsassistent zeigt im Datenbank-Schritt das SQL, mit dem Ihr Datenbank-Team Datenbank und Benutzer vorab anlegt.
| Datenbank | Mindestversion (empfohlen) | getestet gegen |
|---|---|---|
| MySQL | 8.0 | 8.4 |
| PostgreSQL | 14 | 16 |
| Oracle | 19c | XE 21c |
| Microsoft SQL Server | 2019 | 2022 |
Für MySQL gilt: Zeichensatz utf8mb4. Für Oracle: ein eigenes, leeres
Schema, nicht SYSTEM. Mehr dazu unter Datenbank.
MySQL ohne SSL-Angabe verlangt eine verschlüsselte Verbindung
Steht in der Datenbank-Adresse keine SSL-Angabe, verbindet KCForms nur
verschlüsselt (TLS). MySQL 8 kann das von Haus aus. Ein MariaDB-Server in
der Grundeinstellung kann es nicht, und dann startet KCForms nicht. Hängen
Sie in diesem Fall useSSL=false an die Adresse an, oder richten Sie TLS
am Server ein. Der Installationsassistent trägt useSSL=false bereits
ein.
Datenbank-Treiber¶
Was mitgeliefert wird¶
Diese Treiber stecken in ROOT.war:
| Datenbank | Treiber | Version | Lizenz |
|---|---|---|---|
| MySQL und MariaDB | MariaDB Connector/J | 3.5.10 | LGPL 2.1 |
| PostgreSQL | PostgreSQL JDBC | 42.7.4 | BSD |
| Microsoft SQL Server | Microsoft JDBC Driver | 12.6.4 | MIT |
| Oracle | Oracle JDBC (ojdbc11) |
23.4 | Oracle Free Use Terms |
Den Treiber von Oracle für MySQL (MySQL Connector/J) liefern wir nicht
mit. Er steht unter der GPL, und deren Ausnahme gilt nur für
Open-Source-Software. Für MySQL ist das kein Nachteil: KCForms verbindet sich
über den MariaDB-Treiber. Eine Adresse mit jdbc:mysql: gilt wie gewohnt.
Wann Sie einen Treiber selbst ablegen¶
Mit dem Installationsassistenten oder einer bootstrap.properties legen Sie
keinen Treiber selbst ab. Nötig ist das nur in zwei Fällen:
| Fall | Was Sie ablegen |
|---|---|
| A. Sie möchten MySQL über den Treiber von Oracle betreiben statt über MariaDB. | MySQL Connector/J |
B. Tomcat stellt die Datenbank als JNDI-Ressource bereit (<Resource> in ROOT.xml). |
den Treiber Ihrer Datenbank |
Im Fall B gilt das für jede Datenbank, nicht nur für MySQL. Den Verbindungspool baut dann Tomcat selbst, und Tomcat sieht die Treiber im WAR nicht.
Download¶
Nehmen Sie möglichst dieselbe Version, mit der KCForms getestet ist:
| Treiber | Datei zum direkten Herunterladen | beim Hersteller |
|---|---|---|
| MySQL Connector/J (Fall A) | mysql-connector-j-8.3.0.jar | MySQL-Downloadseite |
| MariaDB Connector/J | mariadb-java-client-3.5.10.jar | MariaDB-Downloadseite |
| PostgreSQL | postgresql-42.7.4.jar | PostgreSQL-Downloadseite |
| SQL Server | mssql-jdbc-12.6.4.jre11.jar | Microsoft-Downloadseite |
| Oracle | ojdbc11-23.4.0.24.05.jar | Oracle-Downloadseite |
Die Direkt-Links führen ins öffentliche Maven-Central-Verzeichnis und liefern genau die eine JAR-Datei. Auf der Downloadseite von MySQL wählen Sie „Platform Independent“; dort liegt die JAR-Datei in einem ZIP-Archiv.
MySQL Connector/J ist mit Version 8.3.0 getestet. Eine neuere Version ist wahrscheinlich ebenso geeignet, aber nicht nachgemessen.
Lizenz von MySQL Connector/J
Wer Connector/J selbst herunterlädt und einsetzt, nutzt ihn unter den Bedingungen, die Oracle dafür stellt (GPL, alternativ eine kommerzielle Lizenz von Oracle). KCForms gibt ihn nicht weiter. Klären Sie den Einsatz deshalb bei Bedarf mit Ihrer Lizenzverwaltung.
Ablage¶
Die JAR-Datei gehört in den Ordner lib von Tomcat ($CATALINA_BASE/lib/),
nicht ins WAR und nicht nach webapps:
| System | typischer Ordner |
|---|---|
Linux (Debian-/Ubuntu-Paket tomcat10) |
/usr/share/tomcat10/lib/ |
| Linux (ZIP von apache.org) | <Tomcat-Ordner>/lib/, z. B. /opt/tomcat/lib/ |
| Windows (Installer) | C:\Program Files\Apache Software Foundation\Tomcat 10.1\lib\ |
Danach:
- Prüfen Sie, dass der Benutzer, unter dem Tomcat läuft, die Datei lesen
darf. Unter Linux z. B. mit
chmod 644. - Legen Sie je Treiber nur eine Version ab. Zwei Versionen desselben Treibers nebeneinander führen zu Fehlern, die vom Zufall abhängen.
- Starten Sie Tomcat neu. Ein neu abgelegter Treiber wird erst beim Start geladen.
Prüfen, welcher Treiber spricht¶
Nach dem Start steht im Protokoll ($KCFORMS_HOME/logs/ bzw. das
Tomcat-Protokoll) eine Zeile mit dem tatsächlich verwendeten Treiber:
Haben Sie im Fall A Connector/J abgelegt, steht dort
MySQL Connector/J mysql-connector-j-8.3.0. Steht dort weiter MariaDB, hat
Tomcat die Datei nicht gefunden. Prüfen Sie dann Ordner und Leserechte, und
ob Tomcat neu gestartet ist.
Liegt Connector/J im Ordner lib, nimmt KCForms ihn für die eigene
Datenbank und für alle externen Datenquellen
vom Typ MySQL.
Netzwerk¶
| Richtung | Wozu | Standard-Port |
|---|---|---|
| Browser → Tomcat | Bedienung von KCForms | 8080 (Tomcat), in der Regel hinter einem Reverse-Proxy auf 443 |
| Tomcat → Datenbank | eigene Daten | MySQL 3306, PostgreSQL 5432, Oracle 1521, SQL Server 1433 |
| Tomcat → Mailserver | Benachrichtigungen, optional | 25 / 587 |
| Tomcat → LDAP | Anmeldung und Abgleich, optional | 389 / 636 |