Installation mit Docker¶

Mit Docker installieren Sie KCForms auf einem eigenen Server, ohne Java, Tomcat oder eine Datenbank selbst einzurichten. Sie laden ein ZIP-Paket herunter, starten ein Skript, und ein Assistent im Browser erledigt den Rest.

Diese Seite ist für Administratoren. Sie brauchen keine Kenntnisse über KCForms, aber Sie sollten wissen, wie man sich an einem Server anmeldet und Befehle eingibt.

Lieber ohne Docker?

KCForms läuft auch auf einem vorhandenen Tomcat. Das steht unter Installation auf Tomcat.

Was Sie brauchen¶


Server	Linux, Windows Server oder ein NAS, auf dem Docker läuft
Docker	Docker Engine oder Docker Desktop, dazu Docker Compose Version 2 (der Befehl heißt `docker compose`, mit Leerzeichen)
Arbeitsspeicher	4 GB
Platz	10 GB frei
Internet	beim ersten Start, damit Docker die Bausteine Tomcat und MySQL holen kann
Zugangsdaten	für die Download-Seite, bekommen Sie von Kehrmann Consulting

Ob Docker bereit ist, prüfen Sie mit:

docker compose version

Kommt eine Versionsnummer, ist alles da.

1. Paket herunterladen¶

Die Download-Seite ist https://get.kcforms.kehrmann-consulting.net/. Melden Sie sich mit Ihren Zugangsdaten an und laden Sie das neueste Paket. Es heißt zum Beispiel kcforms-docker-0.1.0-20261105.zip. Die Zahl hinter docker- ist die Version.

Sie können das Paket auch direkt auf den Server laden. Unter dieser Adresse liegt immer die neueste Fassung:

wget --user=IHR-NAME --ask-password \
  https://get.kcforms.kehrmann-consulting.net/latest/kcforms-docker.zip

Prüfen Sie das Paket. Neben jeder Version steht eine Prüfsumme (SHA-256). Sie muss genau zu Ihrer Datei passen. Sonst ist beim Herunterladen etwas schiefgegangen.

LinuxWindows

sha256sum kcforms-docker-*.zip

Get-FileHash .\kcforms-docker-*.zip -Algorithm SHA256

2. Entpacken¶

Das Paket enthält einen Ordner mit der Version im Namen. Legen Sie ihn an seinen festen Platz, zum Beispiel /opt/kcforms. In diesem Ordner bleibt KCForms auch nach Updates.

LinuxWindows

unzip kcforms-docker-*.zip
sudo mv kcforms-*/ /opt/kcforms
cd /opt/kcforms

Rechtsklick auf das ZIP → Alle extrahieren. Den Ordner danach zum Beispiel nach C:\KCForms verschieben und dort eine PowerShell öffnen.

3. Installation starten¶

LinuxWindows

sudo sh install.sh

sudo brauchen Sie nur, wenn Ihr Benutzer Docker nicht ohne sudo benutzen darf.

powershell -ExecutionPolicy Bypass -File .\install.ps1

Das Skript fragt zwei Dinge:

Frage	Was Sie eintragen
Port	die Nummer, unter der KCForms auf dem Server antwortet. Vorgabe: `8080`
Adresse für Ihre Benutzer	so, wie Ihre Benutzer KCForms später aufrufen, zum Beispiel `https://formulare.firma.se`. Ohne Eingabe gilt `http://localhost:8080`

Danach arbeitet es von allein:

Es prüft das Paket.
Es legt die Datei .env mit sicheren Zufalls-Passwörtern an.
Es lädt Tomcat und MySQL und startet KCForms.
Es wartet, bis KCForms antwortet. Beim ersten Mal dauert das 1 bis 3 Minuten.

Am Ende steht da:

KCForms laeuft:  http://localhost:8080/
Setup-Token:     OM7LZWeV0gyokspdee7-xGwc2ZkKHfgH

Das Token brauchen Sie im nächsten Schritt.

4. Einrichten im Browser¶

Öffnen Sie die Adresse im Browser. Der Einrichtungs-Assistent erscheint.

Willkommen: das Setup-Token eingeben.
Administrator: Ihr erstes Konto anlegen. Merken Sie sich das Passwort gut.
System & Design: Name, Adresse, Sprache und Farben.
Abschluss: prüfen und Installation abschließen.

Die Datenbank fragt der Assistent nicht ab. Das hat das Skript schon erledigt. Danach melden Sie sich mit dem neuen Konto an.

Ohne Token keine Einrichtung

Das Token schützt den Server, solange es noch keinen Administrator gibt. Haben Sie es nicht mehr, zeigt dieser Befehl es noch einmal: docker compose exec app cat /app/conf/setup-token.txt

Was wo liegt¶

Alles gehört in den Installationsordner. Sichern Sie ihn regelmäßig.

Ordner / Datei	Inhalt
`.env`	Ihre Einstellungen: Port, Adresse, Passwörter
`home/`	Bilder, Datei-Bibliotheken, Protokolle, PDF-Ablage
`script-modules/`	eigene Skript-Module (JAR), siehe Skript-Module
`war/ROOT.war`	die Anwendung
`backup/`	Datenbank-Sicherungen, die das Update anlegt
`sbom/`	Liste aller enthaltenen Bibliotheken (SBOM)

Die Datenbank selbst liegt in einem Docker-Speicher namens kcforms_db-data, nicht im Ordner.

Warum der Ordner home/ so wichtig ist

Was ein Benutzer hochlädt, zum Beispiel ein Logo, landet dort. Fehlt der Ordner, liegen die Bilder im Inneren des Containers und sind nach dem nächsten Update weg. Die mitgelieferte Compose-Datei richtet ihn deshalb immer ein. Ändern Sie diese Zeile nicht.

Von außen erreichbar machen (HTTPS)¶

Für den Zugriff aus dem Netz gehört ein HTTPS-Proxy vor KCForms, zum Beispiel Nginx, Traefik, Apache oder der IIS. Er nimmt die verschlüsselten Anfragen an und leitet sie an http://<server>:8080 weiter.

Tragen Sie in der .env ein:

KCFORMS_PUBLIC_URL=https://formulare.firma.se
KCFORMS_FORWARD_HEADERS=framework

Danach: docker compose up -d.

`KCFORMS_FORWARD_HEADERS`	Wann
`framework`	KCForms steht hinter einem Proxy. Ohne diese Einstellung scheitert die Anmeldung.
`none`	KCForms steht ohne Proxy direkt im Netz. Sonst könnte jeder Aufrufer eine falsche Absenderadresse vortäuschen.

Hat das Skript eine Adresse mit https:// bekommen, hat es framework schon gesetzt.

Mails¶

Den Mailserver stellen Sie nach der Einrichtung in KCForms ein: Administration → Mail-Konfiguration. Die .env brauchen Sie dafür nicht.

Eine vorhandene Datenbank nutzen¶

Das Paket bringt MySQL 8.4 mit. Haben Sie schon einen Datenbank-Server (MySQL, PostgreSQL, Oracle oder SQL Server), schalten Sie den mitgelieferten ab. In der .env:

COMPOSE_PROFILES=
KCFORMS_DB_URL=jdbc:postgresql://dbserver:5432/kcforms
KCFORMS_DB_USER=kcforms
KCFORMS_DB_PASSWORD=...

Die Datenbank und den Benutzer legen Sie vorher an. Das SQL dafür steht unter Installation auf Tomcat → Der Datenbank-Schritt.

Update¶

Das neue Paket herunterladen und prüfen (Schritt 1).
In einen anderen Ordner entpacken, nicht über die Installation.
Aus dem neuen Ordner das Update starten und den Installationsordner angeben:

LinuxWindows

unzip kcforms-docker-*.zip -d /tmp/kcforms-neu
cd /tmp/kcforms-neu/kcforms-*
sudo sh update.sh /opt/kcforms

powershell -ExecutionPolicy Bypass -File .\update.ps1 C:\KCForms

Das Skript

sichert vorher die Datenbank nach backup/,
behält die alte Fassung als war/ROOT.war.bak,
holt neue Fassungen von Tomcat und MySQL (darin stecken Sicherheitsupdates),
startet KCForms neu und wartet, bis es wieder antwortet.

Ihre .env, der Ordner home/ und die Datenbank bleiben, wie sie sind. Gibt es in einer neuen Version zusätzliche Einstellungen, nennt das Skript sie. Eintragen müssen Sie sie selbst.

Zurück zur alten Fassung

Im Installationsordner:

cp war/ROOT.war.bak war/ROOT.war
docker compose up -d --force-recreate app

Hat die neue Version die Datenbank schon umgebaut, spielen Sie zusätzlich die Sicherung aus backup/ zurück:

gunzip -c backup/kcforms-<datum>.sql.gz | docker compose exec -T db \
  sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD"'

Tägliche Handgriffe¶

Alle Befehle im Installationsordner:

Aufgabe	Befehl
Protokoll ansehen	`docker compose logs -f app`
Anhalten	`docker compose stop`
Starten	`docker compose up -d`
Zustand	`docker compose ps`
Datenbank sichern	`docker compose exec -T db sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --databases kcforms' \\| gzip > backup/hand.sql.gz`

Nach einem Neustart des Servers startet KCForms von allein. Es wartet dabei bis zu 5 Minuten auf die Datenbank.

Wenn etwas nicht klappt¶

Was Sie sehen	Was hilft
`Docker laeuft nicht`	Docker starten. Unter Linux mit `sudo` aufrufen.
`Pruefsumme stimmt nicht`	Paket noch einmal herunterladen.
`port is already allocated`	Ein anderes Programm benutzt den Port. In der `.env` `KCFORMS_PORT` ändern, dann `docker compose up -d`.
Anmeldung scheitert hinter dem Proxy	`KCFORMS_FORWARD_HEADERS=framework` setzen (siehe oben).
KCForms antwortet nach 6 Minuten nicht	`docker compose logs app` ansehen und die letzten Zeilen an den Support schicken.

Passwörter in der .env nachträglich ändern

MySQL übernimmt die Passwörter nur beim allerersten Start. Ändern Sie sie später in der .env, passt KCForms nicht mehr zur Datenbank. Das Passwort ändern Sie deshalb zuerst in MySQL und erst danach in der .env.