Installation auf Tomcat (WAR)¶

Für den Produktivbetrieb wird KCForms als eine Datei ROOT.war auf einem Apache Tomcat 10 installiert. Frontend und Backend stecken beide darin; das Backend liefert die Oberfläche unter / selbst aus. Beim ersten Start ohne Datenbank führt ein Installationsassistent durch die Einrichtung.

Am einfachsten ist die Installation mit Docker: Sie bringt Tomcat und Datenbank gleich mit.

Vorher: Voraussetzungen prüfen

Java 21, Tomcat 10.1 und eine leere Datenbank müssen bereitstehen. Was genau, und wann Sie zusätzlich einen Datenbank-Treiber ablegen, steht unter Voraussetzungen.

WAR beziehen¶

Die fertige ROOT.war steckt im Docker-Paket von der Download-Seite https://get.kcforms.kehrmann-consulting.net/ (Zugangsdaten von Kehrmann Consulting). Entpacken Sie das ZIP und nehmen Sie daraus war/ROOT.war. Prüfen Sie vorher die Prüfsumme, wie unter Installation mit Docker → Paket herunterladen beschrieben.

Für Entwickler: die WAR selbst bauen

Voraussetzung ist nur Docker Desktop. Im Repo-Wurzelverzeichnis:

.\scripts\build-war.ps1

(oder Doppelklick auf scripts\build-war.bat). Der erste Lauf dauert einige Minuten, Folgeläufe deutlich weniger. Ergebnis:

Datei	Inhalt
`install\ROOT.war`	das neue Paket
`install\ROOT-pre-<Datum>.war`	Sicherung des vorherigen Pakets
`install\sbom\`	Stückliste (SBOM) und Prüfsummen

Intern baut Dockerfile.war in drei Stufen: das Frontend mit Node, das Backend mit Maven (-Pwar, der eingebettete Tomcat bleibt draußen) und zuletzt eine Export-Stufe, die nur ROOT.war auf die Festplatte schreibt. Das Kundenpaket für Docker entsteht danach mit .\scripts\package-docker.ps1, veröffentlicht wird es mit .\scripts\publish-download.ps1.

Auf Tomcat bereitstellen¶

Tomcat stoppen.
webapps/ROOT.war und den Ordner webapps/ROOT/ löschen.
Das neue ROOT.war nach webapps/ kopieren.
Nur falls nötig: den Datenbank-Treiber nach lib/ legen. Das betrifft MySQL mit dem Treiber von Oracle oder eine Datenbank per JNDI; alle übrigen Fälle brauchen das nicht. Download und Ablage stehen unter Voraussetzungen → Datenbank-Treiber. Der Treiber bleibt über spätere Updates hinweg liegen, weil er nicht im WAR steckt.
Tomcat starten. KCForms ist unter http://<host>:<port>/ erreichbar.
Im Protokoll prüfen, welcher Treiber spricht. Die Zeile erscheint nach dem Start im Normalbetrieb, nicht im Einrichtungsmodus:
```
Datenbank-Treiber: MariaDB Connector/J 3.5.10 → MySQL 8.4.8
```

Das KCForms-Home-Verzeichnis¶

Alles, was ein neues Deployment überleben muss, liegt außerhalb von Tomcat in einem eigenen Verzeichnis (Muster wie bei Jenkins oder Jira):

Einstellung	Wirkung
`KCFORMS_HOME` (Umgebung) oder `-Dkcforms.home=…`	Basisverzeichnis; Standard `~/.kcforms`

Darunter legt KCForms an:

Ordner	Inhalt
`conf/`	`bootstrap.properties` (Datenbank-Zugang) und `setup-token.txt`
`logs/`	Protokolle
`data/`, `assets/`, `script-libs/`, `pdf/`, `tmp/`	Laufzeit-Dateien

Die Dateien in conf/ werden — wo das Dateisystem es erlaubt — nur für den Tomcat-Benutzer lesbar gespeichert.

Der Installationsassistent¶

Startet KCForms ohne konfigurierte Datenbank, bootet es in einen schlanken Einrichtungsmodus und zeigt unter / den Assistenten. Die Schritte:

Schritt	Inhalt
Willkommen	Setup-Token eingeben, Home-Verzeichnis prüfen
Datenbank	Hersteller (MySQL, PostgreSQL, Oracle, SQL Server), Host, Port, Datenbank, Benutzer; Verbindung testen. Der Assistent zeigt auf Wunsch das SQL, mit dem ein DBA Datenbank und Benutzer anlegt.
Administrator	das erste Admin-Konto
System & Design	Systemname und -kennung, öffentliche Adresse, Standardsprache, Markenfarben, optional Demo-Formulare
Abschluss	Zusammenfassung, dann Installieren

Beim Installieren schreibt der Assistent conf/bootstrap.properties, legt das Datenbank-Schema an, erzeugt das Admin-Konto und speichert die Einstellungen. Danach: Tomcat neu starten — KCForms bootet normal, und der Assistent ist gesperrt.

Setup-Token

Damit niemand im Netz eine frische Installation übernehmen kann, verlangt der Assistent ein Token. Es steht in conf/setup-token.txt und im Tomcat-Log. Nur in abgeschotteten Netzen abschaltbar: KCFORMS_SETUP_TOKEN_REQUIRED=false.

Der Datenbank-Schritt¶

Im Datenbank-Schritt wählen Sie zuerst den Datenbanktyp. Der Assistent setzt dann den passenden Standard-Port und baut aus Host, Port und dem Feld Datenbank / Service die Verbindungsadresse. Einen Treiber legen Sie dafür nicht ab, alle vier stecken im WAR.

Datenbank und Benutzer müssen vorher existieren. Unter Schema anlegen (als root/SYSTEM auszuführen) zeigt der Assistent das SQL dafür, bereits mit Ihren Eingaben gefüllt. Geben Sie es Ihrem Datenbank-Team oder führen Sie es selbst als Administrator aus, bevor Sie auf Verbindung testen klicken.

MySQL / MariaDBPostgreSQLOracleSQL Server

Feld	Eintrag
Port	3306
Datenbank / Service	Name der Datenbank, z. B. `kcforms`

Erzeugte Adresse:

jdbc:mysql://<host>:3306/kcforms?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true&characterEncoding=UTF-8

SQL aus dem Assistenten (als root):

CREATE DATABASE IF NOT EXISTS `kcforms` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'kcforms'@'%' IDENTIFIED BY '<passwort>';
GRANT ALL PRIVILEGES ON `kcforms`.* TO 'kcforms'@'%';
FLUSH PRIVILEGES;

KCForms verbindet sich über den mitgelieferten MariaDB-Treiber. Sie wählen trotzdem diesen Eintrag, die Adresse beginnt weiter mit jdbc:mysql:. Liegt MySQL Connector/J im Ordner lib von Tomcat, nimmt KCForms nach dem Neustart diesen. Am Assistenten ändert sich dadurch nichts.

Die Adresse enthält useSSL=false, die Verbindung ist also unverschlüsselt. Soll sie verschlüsselt sein, tragen Sie unter Erweitert: JDBC-URL überschreiben eine eigene Adresse ohne diese Angabe ein. Einzelheiten unter Voraussetzungen → Datenbank.

Feld	Eintrag
Port	5432
Datenbank / Service	Name der Datenbank, z. B. `kcforms`

Erzeugte Adresse:

jdbc:postgresql://<host>:5432/kcforms

SQL aus dem Assistenten (als Superuser, z. B. postgres):

CREATE USER kcforms WITH PASSWORD '<passwort>';
CREATE DATABASE kcforms OWNER kcforms ENCODING 'UTF8';
GRANT ALL PRIVILEGES ON DATABASE kcforms TO kcforms;

Weil der Benutzer die Datenbank besitzt, darf er darin Tabellen anlegen. Das ist ab PostgreSQL 15 wichtig: Dort darf ein gewöhnlicher Benutzer im Schema public sonst nichts mehr anlegen.

Feld	Eintrag
Port	1521
Datenbank / Service	der Service-Name der Datenbank, z. B. `XEPDB1` oder `ORCLPDB1`, nicht der Name des Schemas
Benutzer	der Benutzer, dem das Schema gehört, z. B. `kcforms`

Erzeugte Adresse:

jdbc:oracle:thin:@<host>:1521/XEPDB1

Bei Oracle ist das Schema der Benutzer. Ein eigenes Datenbank-Feld gibt es dafür nicht: KCForms legt seine Tabellen im Schema des Benutzers an, mit dem es sich anmeldet. SQL aus dem Assistenten (als SYSTEM oder anderer DBA, in der richtigen Pluggable Database):

CREATE USER kcforms IDENTIFIED BY "<passwort>"
    DEFAULT TABLESPACE USERS TEMPORARY TABLESPACE TEMP
    QUOTA UNLIMITED ON USERS;
GRANT CONNECT, RESOURCE TO kcforms;

Nicht als SYSTEM verbinden

Das Schema muss leer sein. In einem Schema mit Tabellen, etwa dem von SYSTEM, überspringt die Schema-Anlage ihren ersten Schritt, und die Kern-Tabellen entstehen nicht. Melden Sie KCForms deshalb immer mit dem eigenen Benutzer an.

Wer statt eines Service-Namens eine SID verwenden muss (ältere Installationen), trägt unter Erweitert: JDBC-URL überschreiben eine Adresse der Form jdbc:oracle:thin:@<host>:1521:<SID> ein (Doppelpunkt statt Schrägstrich). Ab Oracle 12.2 dürfen Tabellennamen 128 Zeichen lang sein. Bei älteren Versionen sind es nur 30; das läuft, macht die Namen aber unleserlich, siehe Datenbank.

Feld	Eintrag
Port	1433
Datenbank / Service	Name der Datenbank, z. B. `kcforms`
Benutzer	ein SQL-Server-Login, z. B. `kcforms`

Erzeugte Adresse:

jdbc:sqlserver://<host>:1433;databaseName=kcforms;encrypt=false

SQL aus dem Assistenten (als sa oder anderes Mitglied von sysadmin):

CREATE DATABASE [kcforms];
GO
CREATE LOGIN [kcforms] WITH PASSWORD = '<passwort>';
GO
USE [kcforms];
CREATE USER [kcforms] FOR LOGIN [kcforms];
ALTER ROLE db_owner ADD MEMBER [kcforms];
GO

Drei Dinge, an denen es in der Praxis hakt:

Das Passwort darf den Login-Namen nicht enthalten. Die Passwort-Richtlinie von SQL Server verbietet das. Die Fehlermeldung sagt nur „not complex enough“ und nennt diesen Grund nicht. Gemessen scheiterte Kcfw!Test2026x für den Login kcfw, obwohl es lang genug ist und alle vier Zeichengruppen enthält.
Eine benannte Instanz (etwa SQLEXPRESS) lauscht oft nicht auf 1433, sondern auf einem wechselnden Port. Tragen Sie dann den Port ein, den der SQL Server Configuration Manager unter TCP/IP anzeigt, oder stellen Sie dort einen festen Port ein. Außerdem muss TCP/IP eingeschaltet sein; bei Express ist es das anfangs nicht.
SQL-Server-Anmeldung muss erlaubt sein (gemischter Modus). Mit reiner Windows-Anmeldung kann sich KCForms nicht anmelden.

Die Adresse enthält encrypt=false. Verlangt Ihr Server eine verschlüsselte Verbindung, tragen Sie unter Erweitert: JDBC-URL überschreiben eine eigene Adresse mit encrypt=true ein.

Verbindung testen öffnet eine Verbindung mit genau diesen Angaben. Erst wenn der Test grün ist, geht es weiter. Die Tabellen legt KCForms nicht im Assistenten an, sondern beim Start nach dem Neustart.

Gemessen

Für PostgreSQL 16, Oracle XE 21c und SQL Server 2022 sind Adresse und SQL-Vorlage am 18.10.2026 nachgeprüft: Benutzer mit genau diesen Rechten angelegt, KCForms mit der Adresse des Assistenten gestartet, Tabellen angelegt, Anmeldeseite erreichbar. Durchgeklickt wurde dabei nicht der Assistent selbst, sondern der Start mit der Adresse, die er in bootstrap.properties schreibt. MySQL ist die Standard-Datenbank und wurde bei dieser Gelegenheit nicht eigens nachgemessen.

Datenbank schon per JNDI vorhanden

Stellt Tomcat die Datenbank bereits als JNDI-Ressource bereit, entfällt der Datenbank-Schritt. Der Assistent legt dann nur Admin und Einstellungen an — ohne Neustart. Den Treiber für diese Ressource müssen Sie selbst nach lib/ legen, siehe Voraussetzungen, Fall B. Eine Vorlage für die Ressource liegt als dist/tomcat/ROOT.xml im Repository.

Unbeaufsichtigte Installation¶

Für automatisierte Deployments lassen sich alle Werte vorab setzen — in conf/bootstrap.properties, als Systemeigenschaft oder als Umgebungsvariable. Beim ersten Start mit Datenbank richtet KCForms sich dann selbst ein. Das Beispiel unten nutzt PostgreSQL. Für die anderen Datenbanken ändert sich nur die erste Zeile; Datenbank und Benutzer legen Sie vorher mit dem SQL aus dem Datenbank-Schritt an.

MySQL / MariaDBPostgreSQLOracleSQL Server

spring.datasource.url=jdbc:mysql://db.example.local:3306/kcforms?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true

Ohne useSSL=false verlangt KCForms eine verschlüsselte Verbindung, siehe Voraussetzungen → Datenbank.

spring.datasource.url=jdbc:postgresql://db.example.local:5432/kcforms

spring.datasource.url=jdbc:oracle:thin:@db.example.local:1521/ORCLPDB1

ORCLPDB1 ist der Service-Name. Als spring.datasource.username steht der Benutzer, dem das leere Schema gehört.

spring.datasource.url=jdbc:sqlserver://db.example.local:1433;databaseName=kcforms;encrypt=false

Im Format von SQL Server stehen die Optionen hinter Semikolons, nicht hinter ? und &.

Die vollständige Datei:

spring.datasource.url=jdbc:postgresql://db.example.local:5432/kcforms
spring.datasource.username=kcforms
spring.datasource.password=…

kcforms.setup.adminUser=admin
kcforms.setup.adminPassword=…
kcforms.setup.adminFirstName=Hans
kcforms.setup.adminLastName=Administrator
kcforms.setup.adminEmail=admin@example.com
kcforms.setup.systemName=KCForms
kcforms.setup.systemId=kcforms-prod
kcforms.setup.publicBaseUrl=https://forms.example.com
kcforms.setup.defaultLang=de
kcforms.setup.brandPrimary=#003769
kcforms.setup.brandSecondary=#ffc301
kcforms.setup.seedExamples=false

Nach erfolgreicher Einrichtung entfernt KCForms die kcforms.setup.*-Werte aus der bootstrap.properties; nur der Datenbank-Zugang (spring.datasource.*) bleibt stehen.

Demo-Konten¶

Eine Tomcat-Installation bekommt keine Demo-Konten (kcforms.demo.users ist aus). Das einzige Konto ist der Administrator aus dem Assistenten bzw. aus kcforms.setup.adminUser.

Welche Datenbank wie angebunden wird, steht unter Datenbank.