Betrieb unter Docker

Geändert am Di, 4 Nov um 1:10 NACHMITTAGS

Sollten Sie formcycle innerhalb einer Docker-Umgebung betreiben wollen, stehen Ihnen hierfür die entsprechenden Images zur freien Verfügung. Diese basieren auf einem Tomcat-Image inkl. Java 17 und sind so weit wie möglich und sinnvoll bereits gehärtet. Hierbei wird formcycle im Root-Kontext, also ohne Anwendungspfad betrieben und ist über den Container-Port 8080 erreichbar. Ferner werden etwaige "x-forwarded"-Header für einen Betrieb hinter z.B. einem Proxy-Server standardmäßig interpretiert.

Wichtiger Hinweis: Sofern Sie formcycle unter Docker verwenden möchten, wenden Sie sich bitte an Ihren organisatorischen Ansprechpartner, damit Ihre Lizenz entsprechend angepasst werden kann.

Inhalt

1. Verfügbare Docker-Images
- xima/formcycle
- xima/formcycle/frontend-server
2. Beziehen der Docker-Images
- Aktuell verfügbare Tags
3. Der Konfigurations-Ordner /xima
4. Der Konfigurations-Ordner /tomcat
5. Standard-Installation
6. Zusätzliche Hinweise
7. Monitoring und Metriken
8. Installation von Zertifikaten
9. Konfiguration von formcycle
10. Konfiguration von Tomcat
11. Migration einer bestehenden Installation
12. Erweitere Informationen
- Daten-Verzeichnis /xima-data

1. Verfügbare Docker-Images

Es stehen Ihnen insgesamt zwei verschiedene Images zur Verfügung:

xima/formcycle

Hierbei handelt es sich um den formcycle Master-Server, welcher das komplette Formular-Management, die Workflow-Verarbeitung und die Verwaltungsoberfläche bereitstellt.

xima/formcycle/frontend-server

Hierbei handelt es sich um einen formcycle Frontend-Server, welcher je nach Konfiguration mindestens die Funktionalitäten für die Auslieferung und Entgegennahme von Formularen und ggf. auch das Sachbearbeiter-Postfach bereitstellt.

2. Beziehen der Docker-Images

Bezogen werden können diese Images über die Registry docker.formcycle.eu. Als Image-Tags kommen die entsprechenden formcycle-Versionen zum Einsatz.

Beispiel:

Das Image xima/formcycle:8.3.0 stellt einen formcycle Master-Server in der Version 8.3.0 bereit und kann über docker.formcycle.eu/xima/formcycle:8.3.0 bezogen werden.

Ferner werden die Images zusätzlich mit dem spezifischeren Tag inkl. Version der Tomcat-Image bereitgestellt:

Beispiel:

Das Image xima/formcycle:8.3.0-9.0.98-jre17 stellt einen formcycle Master-Server in der Version 8.3.0 basierend auf einem Tomcat 9.0.98 und Java 17 bereit und kann über docker.formcycle.eu/xima/formcycle:8.3.0-9.0.98-jre17 bezogen werden.

Es wird empfohlen immer Images ohne die Angabe der Tomcat-Version zu verwenden. Dies ermöglicht eine einfachere Aktualisierung der Image durch den Neustart des Containers.

Aktuell verfügbare Tags

Allg. Tag	Tag-Varianten
8.4.2	8.4.2-9.0.111-jre17
8.4.1	8.4.1-9.0.111-jre17
8.4.0	8.4.0-9.0.108-jre17 \| 8.4.0-9.0.109-jre17 \| 8.4.0-9.0.111-jre17
8.3.9	8.3.9-9.0.109-jre17 \| 8.3.9-9.0.111-jre17
8.3.8	8.3.8-9.0.106-jre17 \| 8.3.8-9.0.108-jre17 \| 8.3.8-9.0.109-jre17
8.3.7	8.3.7-9.0.106-jre17
8.3.6	8.3.6-9.0.100-jre17 \| 8.3.6-9.0.105-jre17
8.3.5	8.3.5-9.0.100-jre17
8.3.4	8.3.4-9.0.98-jre17
8.3.3	8.3.3-9.0.98-jre17
8.3.2	8.3.2-9.0.99-jre17 \| 8.3.2-9.0.98-jre17
8.3.1	8.3.1-9.0.98-jre17
8.3.0	8.3.0-9.0.98-jre17
8.2.6	8.2.6-9.0.98-jre17
8.2.5	8.2.5-9.0.97-jre17 \| 8.2.5-9.0.98-jre17
8.2.4	8.2.4-9.0.97-jre17 \| 8.2.4-9.0.98-jre17
8.2.3	8.2.3-9.0.93-jre17 \| 8.2.3-9.0.95-jre17 \| 8.2.3-9.0.96-jre17 \| 8.2.3-9.0.97-jre17 \| 8.2.3-9.0.98-jre17
8.2.2	8.2.2-9.0.93-jre17
8.2.1	8.2.1-9.0.93-jre17

3. Der Konfigurations-Ordner /xima

Für die persistente Konfiguration wird innerhalb des Containers der Ordner /xima verwendet. Dieser ist darauf ausgelegt, dass diese in den Host oder als persistentes Volume gemountet wird und somit den Neustart von Containern überdauert (siehe Beispiele). In diesem Ordner können bzw. werden zum Teil durch formcycle selbst folgende Unterornder angelegt:

/xima/config

Beinhaltet die eigentlichen formcycle-Konfigurationsdateien

/xima/prefs

Beinhaltet die Java Preferences-Konfiguration

/xima/drivers

Dient der Ablage von zu verwendeten Datenbank-Treibern

/xima/certificates

Dient der Ablage zu installierenden Zertifikaten (*.crt, *.cer, *.pem) oder eines zu verwendenden Java Keystores

4. Der Konfigurations-Ordner /tomcat

Neben Um eine Konfigurationsmöglichkeit des Tomcat-Servers zu gewährleisten, kann der Ornder /tomcat innerhalb des Containers verwendet werden. Dieser kann neben zusätzlichen Anwendungen und Bibliotheken auch Konfigurationsdateien beinhalten. Diese Dateien werden alle beim Start des Containers an die dafür vorgesehenen Stellen kopiert.

Die vom Container-Skript angedachte Ablagestruktur sieht hierbei wie folgt aus:

/tomcat/config

Dient der Ablage von Tomcat-Konfigurationsdateien

/tomcat/libs

Dient der Ablage von weiteren zu verwendenden Java-Bibliotheken

/tomcat/webapps

Ermöglicht die Ablage von weiteren Webanwendungen (*.war-Dateien) welche im Tomcat installiert werden sollen

5. Standard-Installation

Mit folgendem Aufruf starten Sie einen Master-Server mit persistenter Konfiguration:

docker run -d -p 9080:8080 --name formcycle --restart=always --pull=always -v /docker-vol/formcycle:/xima docker.formcycle.eu/xima/formcycle:8.3.0

Hier wird formcycle in der Version 8.3.0 in einem Container mit dem Namen formcycle gestartet. Formcycle ist anschließend über den Port 9080 des Hosts erreichbar (http(s)://<host>:9080/). Die Konfiguration von formcycle wird im Host-Verzeichnis /docker-vol/formcycle abgelegt. Zu beachten ist, dass der notwendige Datenbank-Treiber in den Ordner /docker-vol/formcycle/drivers abgelegt werden muss.

Bestandteile des Standardaufrufs

Bestandteil des Aufrufs	Beschreibung
docker run -d	Startet den Docker Container als Dienst
-p 9080:8080	Gibt den Port 8080 des Containers als Port 9080 frei
--name formcycle	Benennt den Container "formcycle"
--restart=always	Startet den Container automatisch neu falls dieser stoppen sollte
--pull=always	Aktualisiert ggf. die Image vor dem Start des Containers
-v /docker-vol/formcycle:/xima	Mountet den Ordner "/docker-vol/formcycle" des Hosts in den Container unter "/xima"
docker.formcycle.eu/xima/formcycle:8.3.0	Gibt das zu verwendende Image an

Achtung: Werden die Konfigurations-Ordner dem Container mittels bind-mount
bereitgestellt, ist darauf zu achten, dass dieser Ordner für den Benutzer innerhalb des Containers die entsprechenden Berechtigungen (Lesen und Schreiben) besitzt. Hierbei handelt es sich standardmäßig um den Benutzer ubuntu:ubuntu (1000:1000).

Starten eines Frontend-Servers

Sollten Sie einen Frontend-Server starten wollen, ist dieses ähnlich dem Starten des Master-Servers wie folgt möglich:

docker run -d -p 9081:8080 -p 4753:4753 --name frontend-server --restart=always --pull=always -v /docker-vol/frontend-server:/xima docker.formcycle.eu/xima/formcycle/frontend-server:8.3.0

Neben der Angabe eines anderen Persistenz-Ordners, eines anderen Container-Namens und der Verwendung des Frontend-Server-Images, kann es notwendig sein, dass der entsprechende Port für das Herstellen einer Verbindung durch einen Master-Server freigegeben werden muss. Dies ist nur der Fall, wenn der Frontend-Server nicht auf demselben Docker-Host innerhalb desselben Docker-Netzwerks betrieben werden soll. In diesem Beispiel wir der Standardport 4753 (-p 4753:4753) nach außen durchgereicht.

6. Zusätzliche Hinweise

Beim Betrieb von formcycle innerhalb einer Container-Umgebung gibt es einige Punkte die je nach Szenario beachtet werden müssen. Diese sind hierbei folgende:

Für den Container-Betrieb ist ein spezieller Lizenz-Typ vorgesehen (Container-Lizenz). Dieser unterscheidet sich von der Standard-Lizenz dahingehend, dass hier keine Bindung basierend auf der Hardware-ID des betreibenden Systems stattfindet. Sollte diese nicht benutzt werden, müsste nach jedem Neustart eines Containers ggf. die Hardware-ID der Lizenz innerhalb von formcycle aktualisiert werden. Grund ist hierfür, dass sich diese bei jedem Neustart eines Containers ändern kann.
Sollten mehrere formcycle-Instanzen betrieben werden, ist darauf zu achten, dass diese als Cluster konfiguriert sind und ein Load-Balancer o.ä. Sticky-Sessions verwendet.
Sollten Frontend-Server zum Einsatz kommen und es dadurch zu einer Mischung zwischen Umgebungen (Container und Standalone) kommen, ist darauf zu achten, dass die Standalone-Umgebung die selbe Java und Tomcat-Version wie die Container-Umgebung verwendet. Durch Updates und sich damit schnell ändernden Versionen in der Container-Umgebung kann dies zu Aufwand führen, weswegen wir von einem Mischbetrieb eher abraten würden.

7. Monitoring und Metriken

Für das Monitoring des Containers und von formcycle wird die Docker-Image standardmäßig mit dem Prometheus JMX-Exporter ausgeliefert. Dieser wird als separater Agent gestartet und ist standardmäßig über den Port 5556 erreichbar. Dieser Port wird aus Sicherheitsgründen standardmäßig nicht freigegeben. Sollte dieser aber erreichbar sein (z.B. innerhalb des selben Docker networks), stellt dieser die Funktionalitäten über eine Web-Schnittstelle zur Verfügung und kann so z.B. mittels Grafana angebunden werden.

8. Installation von Zertifikaten

Im innerhalb des Containers neben den Standard-Zertifikaten auch eigene Zertifikate verwenden zu können, gibt es die Möglichkeit über den Ornder (standardmäßig) /xima/certificates zusätzliche Zertifikate zu installieren. Hierbei werden die Formate *.crt, *.cer, und *.pem unterstützt. Alle Dateien mit diesen Dateiänderungen werden beim Start des Containers unter Verwendung des Dateinamen als Alias in den Standard Keystore von Java importiert. Ferner gibt es alternativ die Möglichkeit in diesem Ornder einen entsprechenden cacerts-Keystore abzulegen. Dieser überschreibt hierbei beim Container-Start den cacerts-Keystore von Java und muss demnach auch das selbe Passwort verwenden (Standard: changeit). Da es sich hierbei um eine Überschreibung handelt ist darauf zu achten, dass man einen entsprechenden Keystore als Grundlage verwendet und diesen nur um weitere Zertifikate ergänzt.

9. Konfiguration von formcycle

Neben der Standard-Konfiguration über die Verwaltungsoberfläche erlaubt es die formcycle Docker-Image auch grundlegende Konfigurationen mittels Environment-Variablen. Hierbei handelt es sich um Parameter, welcher beim Start eines Docker-Containers übergeben werden können. Für die Konfiguration der Datenbank-Anbindung und der automatischen Aktualisierung stehen auf dem Master-Server hierbei folgende Parameter zur Verfügung:

Variable	Erlaubte Wert	Beschreibung
XFC_DATABASE_SHORT_NAME	mysql (Oracle MySQL) mariadb (MariaDB) oracle (Oracle Database) postgresql (PostgreSQL) sqlserver (MS SQL Server)	Legt den Typ der anzubindenen Datenbank fest.
XFC_DATABASE_JDBC_URL	Eine JDBC-URL gemäß der verwendeten Datenbank. Beispiel MySQL: jdbc:mysql://db-server:3306/formcycle	Gibt die JDBC-URL zur Herstellung der Verbindung zur System-Datenbank an.
XFC_DATABASE_LOGIN_USER	(Freitext)	Gibt den zu verwendenden Benutzernamen zur Herstellung der Verbindung zur System-Datenbank an.
XFC_DATABASE_LOGIN_PASSWORD	(Freitext)	Gibt daszu verwendenden Passwort zur Herstellung der Verbindung zur System-Datenbank an.
XFC_DATABASE_POOL_MAX_CONNECTIONS	(Positive Ganzzahlen)	Gibt die max. Größe des zu verwendenden Datenbank-Pools an.
XFC_DATABASE_POOL_CONNECTION_TIMEOUT	(Positive Ganzzahlen)	Gibt an nach wie vielen Sekunden eine ungenutzte Datenbank-Verbindung innerhalb des Pools geschlossen werden soll.
XFC_DATABASE_ENCRYPTION_ALGORITHM	PBE_WITH_MD2_AND_DES PBE_WITH_MD2_AND_RC2 PBE_WITH_MD5_AND_DES PBE_WITH_MD5_AND_RC2 PBE_WITH_SHA1_AND_DES PBE_WITH_SHA1_AND_RC2 PBE_WITH_SHA_AND_2_KEYTRIPLEDES_CBC PBE_WITH_SHA_AND_3_KEYTRIPLEDES_CBC PBE_WITH_SHA_AND_128BITRC2_CBC PBE_WITH_SHA_AND_40BITRC2_CBC PBE_WITH_SHA_AND_128BITRC4 PBE_WITH_SHA_AND_40BITRC4 PBE_WITH_SHA_AND_TWOFISH_CBC PBE_WITH_SHA_AND_IDEA_CBC	Gibt den Algorithmus an, der bei der Anwendungs-seitigen Verschlüsselung von Daten benutzt werden soll.
XFC_DATABASE_ENCRYPTION_PASSWORD	(Freitext)	Gibt das Passwort an, das bei der Anwendungs-seitigen Verschlüsselung von Daten benutzt werden soll.
XFC_DATABASE_ENCRYPT_FORM_DATA	true (aktiviert) false (deaktiviert, standard)	Gibt an, ob Formular-Daten verschlüsselt werden sollen.
XFC_AUTO_UPDATE	true (aktiviert) false (deaktiviert, standard)	Gibt an, ob Datenbank- und System-Aktualisierungen beim Systemstart automatisch ausgeführt werden sollen.
XFC_AUTO_UPDATE_PLUGINS	true (aktiviert) false (deaktiviert, standard)	Gibt an, ob (wenn möglich) Plugin-Aktualisierungen beim Systemstart automatisch ausgeführt werden sollen.
XFC_UPDATE_CALLBACK_EMAILS	Eine einzelne oder Komma-separierte Liste von E-Mail-Adressen. Beispiele: admin@example.com admin1@exampe.com,admin2@example.com	Gibt eine Liste von E-Mail-Adresse an, die nach einer erfolgten automatischen Aktualisierung über deren Durchführung benachritigt werden sollen.

10. Konfiguration von Tomcat

Da die formcycle Docker-Image auf der offiziellen Tomcat Docker-Image basiert stehen neben den Anpassungen, die bereits durch formcycle durchgeführt werden, die Standardwege zur Konfiguration des Tomcat-Servers zur Verfügung. Hierfür können die entsprechenden Variablen der Tomcat Docker-Image benutzt werden:

Variable	Erlaubte Wert	Beschreibung
JAVA_OPTS	(Freitext)	Variable für Java-weiter Konfigurationen wie z.B. die maximale Speichergröße, Garbage Collector-Optionen oder Debug-Parameter. Diese Optionen gelten für jeden Java-Prozess, der gestartet wird.
CATALINA_OPTS	(Freitext)	Variable für weitere, Tomcat-spezifische Konfigurationen. Diese Optionen betreffen nur den Tomcat-Prozess und nicht andere Java-Prozesse im gleichen System.

Achtung: Da auf Grund verschiedenster Umgebungen keine festen Werte bezüglich der Speicherverwendung innerhalb der formcycle Docker-Image festgelegt sind, ist es empfehlenswert diese mittels z.B. JAVA_OPTS zu hinterlegen. Sollte dies nicht hinterlegt sein, greift der Java-Standard, der eine Speicher-Benutzung von max. 25% des physischen Speichers vorsieht. Mehr dazu finden Sie unter Tomcat-Einstellungen.

11. Migration einer bestehenden Installation

Sollten Sie eine bestehende Standalone-Installation von formcycle in eine Container-Umgebung migrieren wollen, ist dies problemlos möglich. Als einziger elementarer Schritt neben der Standardkonfigurationen des Containers sind hier die vorhandenen Konfigurationsdateien in den entsprechenden Ordner für den Container zu kopieren (siehe "3. Der Konfigurations-Ordner /xima"). Je nach getroffenen Anpassungen oder Umstellungen sind ggf. noch folgende Änderungen/Aktionen durchzuführen:

Anpassungen in der server.xml übernehmen (siehe "4. Der Konfigurations-Ordner /tomcat")
Ggf. Anpassung der JDBC-URL und Migration der Einstellungen in ENV-Parameter
Ggf. Anpassung der Monitoring-Anbindungen
Sollten Aktionen Dateien im Dateisystem ablegen, sind hierfür entsprechende Mounts/Volumes zu erstellen
Es ist zu prüfen, dass alle angebundenen Fremdsysteme auch im Container erreichbar sind

12. Erweitere Informationen

Neben der Grundlegenden Konfiguration von formcycle stehen zusätzlich noch weiter Environment-Paramter zur Konfiguration des Containers zur Verfügung:

Variable	Standard-Wert	Beschreibung
TOMCAT_PORT	8080	Gibt den erwarteten Tomcat-Port des Containers an. Dieser wird hauptsächlich für den Healthcheck des Containers benutzt und ist anzupassen so bald eine entsprechende Änderung an der server.xml stattgefunden hat.
TOMCAT_CONFIG_DIR	/tomcat/config	Gibt ein Verzeichnis an unter welchem zusätzlich Tomcat-spezifische Konfigurations-Dateien hinterlegt werden können. Der Inhalt dieses Verzeichnisses wird beim Start in den conf-Ordner das Tomcats kopiert und ermöglicht so das Überschreiben der Server-Konfiguration.
TOMCAT_LIBS_DIR	/tomcat/libs	Gibt ein Verzeichnis an unter welchem zusätzliche Java-Bibliotheken für den Tomcat-Server hinterlegt werden können. Der Inhalt dieses Verzeichnisses wird beim Start in den lib-Ordner des Tomcat-Servers kopiert.
TOMCAT_WEBAPPS_DIR	/tomcat/webapps	Gibt ein Verzeichnis an unter welchem zusätzliche Webanwendungen (*.war) hinterlegt werden können. Diese werden beim Start in den webapps-Ordner des Tomcat-Servers kopiert und stehen gemäß ihrem Namens anschließend neben formcycle zur Verfügung.
XFC_CONFIG_DIR	/xima/config	Gibt das Verzeichnis an unter welchem formcycle die eigenen Konfigurationen speichern und laden soll.
XFC_SYSTEM_PREF_DIR	/xima/prefs/user	Gibt das Verzeichnis an unter welchem Java System-Preferences gespeichert werden sollen
XFC_USER_PREF_DIR	/xima/prefs/system	Gibt das Verzeichnis an unter welchem Java Benutzer-Preferences gespeichert werden sollen
XFC_DRIVERS_DIR	/xima/drivers	Gib das Verzeichnis für zusätzlich zu installierende Datenbank-Treiber an. Der Inhalt dieses Verzeichnisses wird beim Start des Containers in den lib-Ordner des Tomcat-Servers kopiert.
XFC_CERT_DIR	/xima/certificates	Gibt das Verzeichnis für zu installierende Zertifikate (.crt, .cer, *.pem) oder des zu installierenden Keystores an.
XFC_SCAN_DIR	/xima-data/scan	Gibt das Verzeichnis an unter welchem formcycle Dateien für einen Datei-basierend Virenscan ablegen soll.
XFC_TEMP_DIR	/xima-data/temp	Gibt das Verzeichnis an unter welchem formcycle temporäre Dateien ablegen soll.
XFC_DATA_DIR	/xima-data/data	Gibt das Verzeichnis an unter welchem formcycle Lautzeit-Dateien welche zum Beispiel innerhalb des Workflows erzeugt werden ablegen soll.
XFC_PLUGIN_DIR	/xima-data/plugins	Gibt das Verzeichnis an unter welchem formcycle Plugins ablegen soll.
XFC_CACHE_DIR	/xima-data/cache	Gibt das Verzeichnis an unter welchem formcycle seinen Anwendungs-Cache ablegen soll.
JMX_EXPORTER_PORT	5556	Gibt den Port an, über welchen der Prometheus JMX-Exporter zur Verfügung gestellt wird.
JMX_EXPORTER_OPTS	-javaagent:/xima-deployment/jmx_prometheus_javaagent.jar=${JMX_EXPORTER_PORT}:/xima-deployment/jmx-exporter-config.yaml	Gibt die CATALINA_OPTS an, welche für die Definition des Prometheus JMX-Exporters verwendet wird.
JAVA_PREFS_OPTS	-Djava.util.prefs.systemRoot=${XFC_SYSTEM_PREF_DIR} -Djava.util.prefs.userRoot=${XFC_USER_PREF_DIR}	Gibt die CATALINA_OPTS an, welche für das Konfigurieren der Java Preferences-Verzeichnisse benutzt wird.

Eine Änderung der Standard-Konfiguration erfollgt auf eigene Verantwortung und sollte nur in Ausnahmefällen nötig werden.

Daten-Verzeichnis /xima-data

Neben dem Konfigurations-Ornder wird innerhalb des Containers noch das Verzeichnis /xima-data verwendet. In diesem werden Dateien zur Laufzeit des Containers abgelegt und durch formcycle verwaltet. Einzig der Unterordner /xima-data/scan kann hier von Bedeutung sein, da dieser es über einen entsprechenden Mount ermöglicht Uploads aus Formularen oder der Verwaltungsoberfläche mittels Virenscanner zu untersuchen.

Es wird empfohlen die Anbindung von Virenscannern über die dafür vorgesehenen formcycle-Plugins zu realisieren.