Installation auf Tomcat

signoSign/Universal wird gegen die Servlet-Spezifikation 3.0 entwickelt. In diesem Kapitel zeigen wir die Installation der Anwendung am Beispiel eines Tomcat Servlet Containers. Für den Betrieb auf anderen Webservern (z. B. einem Wildfly), folgen Sie bitte den Dokumentationen des jeweiligen Anbieters. Darüber hinaus ist z. B. auch der Betrieb innerhalb eines Docker-Containers möglich.

Bitte beachten Sie zudem, dass diese Anleitung kein Best-Practice darstellt und die Inbetriebnahme und Betreuung durch fachkundige Personen durchgeführt werden sollte. Als Hersteller der Webanwendung übernimmt signotec keine Haftung für fehlerhafte Konfigurationen der IT-Infrastruktur.

Benötigte Software

Die im Folgenden aufgeführten Software-Produkte sind zum Betrieb von signoSign/Universal unbedingt notwendig.  Mit Ausnahme des Datenbankservers müssen Sie auf dem Host installiert werden. Läuft die Datenbank auf einem anderen Host, muss seine Erreichbarkeit sichergestellt sein.

Folgende Komponenten werden benötigt:

• Java 8, 11 oder 17

• Tomcat Servlet Container (8.5.x oder 9.0.x)

• signoSignUniversal.war

• Datenbank (bspw. MySQL)

Java installieren

Installieren Sie Java (s. o.) auf Ihrem System. Sie können Java wahlweise direkt von der Oracle Webseite herunterladen oder unter Linux OpenJDK verwenden.

JAVA_HOME Variable konfigurieren

Konfigurieren Sie die “JAVA_HOME”-Umgebungsvariable. Unter Windows gehen Sie hierzu in die erweiterten Systemeinstellungen (“Windows-Taste + R” → “sysdm.cpl”). Im Reiter “Erweitert” können Sie über den Button “Umgebungsvariablen…” eine neue Variable konfigurieren. Klicken Sie hierzu in dem neuen Fenster auf “Neu…” und geben Sie als Namen der Variable “JAVA_HOME” ein. Der Pfad muss auf das Installationsverzeichnis von Java verweisen, z. B.:

C:\Program Files\Java\jdk1.8.0_XXX

Bestätigen Sie die Eingabe anschließend mit “OK” und schließen Sie die weiteren Fenster.

Tomcat installieren

Laden Sie den Tomcat “Core” in einer der o. g. Versionen auf der offiziellen Apache Tomcat-Webseite herunter. Ob Sie den Tomcat als ZIP oder EXE (Windows Service Installer) nutzen möchten, ist für den Betrieb von signoSign/Universal unerheblich und kann frei von Ihnen gewählt werden. Für eine schnelle Installation, insbesondere zum Testen, ist das ZIP-Paket tendenziell einfacher zu nutzen.

Java 11 Patch

Seit Java 11 sind einige APIs nicht mehr in der Java Runtime enthalten und müssen durch einen Patch in die Anwendung eingefügt werden. Informationen zu den entfernten APIs finden Sie u. a. hier:

https://openjdk.java.net/jeps/320#Java-EE-modules

Inhalt des Patches

Der Patch für die Verwendung von Java 11 befindet sich im Ordner „java11“ des Auslieferungspakets. Es enthält die API-Spezifikationen (webservices-api-[VERSION].jar) und die Implementierung der APIs (webservices-rt-[VERSION].jar).

Alternativ können die Dateien z. B. auch aus dem Maven-Central heruntergeladen werden:

• https://repo1.maven.org/maven2/org/glassfish/metro/webservices-api/[VERSION]

• https://repo1.maven.org/maven2/org/glassfish/metro/webservices-rt/[VERSION]

Anwendung des Patches

Der Patch kann global für alle Anwendungen des Servers, oder für jede einzelne Anwendung installiert werden. Wenn auf dem Server nur signoSign/Universal betrieben wird, empfehlen wir die globale Installation.

Globale Installation

Beim Start des Servers werden die Dateien automatisch geladen und sind für alle Webanwendungen verfügbar. Kopieren Sie hierzu die Dateien in den Ordner „<TOMCAT-HOME>/lib/“.

Individuelle Installation

Der Patch wird zu den Bibliotheken der einzelnen Anwendungen hinzugefügt. Hierzu öffnen Sie die Datei „signoSignUniversal.war“ mit einem ZIP-Programm und kopieren die Dateien des Patches in den Unterordner „WEB-INF/lib/“.

Benutzer anlegen

signoSign/Universal greift standardmäßig auf die Benutzer des Webservers zu. Im Beispiel des Tomcats kann die Quelle für die angelegten Benutzer in der „server.xml“ im Ordner „<TOMCAT-HOME>/conf/“ festgelegt werden. Im Standard nutzt der Tomcat als User- und Rollendatenbank die Datei „tomcat-users.xml“ im Ordner „<TOMCAT-HOME>/conf/“.

Rollen deklarieren

signoSign/Universal unterstützt zwei verschiedene Rollen. Mindestens eine dieser Rollen muss deklariert werden.

Im folgenden Beispiel wird der Benutzer „john“ mit dem Kennwort „password“ und der Rolle „ssu-user“ in der “tomcat-users-xml” angelegt:

<!-- file conf/tomcat-users.xml -->
<tomcat-users>
  <role rolename="ssu-user"/>
  <user username="john" password="password" roles="ssu-user"/>
</tomcat-users>

Es ist möglich auf vorhandene Authentifizierungssysteme zurückzugreifen. Im Tomcat müssen die entsprechende Datenquelle und Realm definiert werden. Weitere Informationen können Sie der Dokumentation von Tomcat Apache entnehmen: https://tomcat.apache.org/tomcat-9.0-doc/realm-howto.html

TLS-Konfiguration (https)

Die Verbindung zu signoSign/Universal über eine gesicherte HTTPS-Verbindung erfordert die ent-sprechende Konfiguration des Webservers (Tomcat) oder eines vorgelagerten Reverse-Proxys (o. ä.).

Für weitere Informationen zur SSL- bzw. TLS-Konfiguration folgen Sie folgendem Link:

https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html

Datenbank

signoSign/Universal benötigt ab Version 3.13.0 eine Datenbank. Im Standard wird eine H2-Datenbank (In-File) verwendet. Diese Datenbank eignet sich nur für sehr einfache Anwendungsfälle und sollte in der Regel nur für Testzwecke verwendet werden. Es wird dringend empfohlen, eine verwaltete Datenbank, wie z.B. MySQL, zu verwenden. Mehr Informationen zur Konfiguration der Datenbank sind im Kapitel “Datenbank konfigurieren” enthalten.

Anwendung konfigurieren

Um Servereinstellungen vorzunehmen, editieren Sie einfach die gewünschten Einstellungen in der „settings.properties“, welche unter „signoSignUniversal.war/WEB-INF/classes“ zu finden ist.

Um die Einstellungen updatesicher zu machen, können einzelne Einstellungen auch als System- oder Umgebungsvariable definiert oder eine externe Konfigurationsdatei erstellt werden.

Webanwendung deployen

Nachdem Sie Java und den Tomcat installiert haben, legen Sie die “signoSignUniversal.war” aus dem Downloadpaket in das /webapps/-Verzeichnis des Tomcat (<TOMCAT-HOME>/webapps).

Starten Sie anschließend den Tomcat über die startup.bat (Linux: startup.sh) bzw. den ggf. konfigurierten/installierten Dienst.

Web-Ressourcen aufrufen

Nachdem der Tomcat gestartet hat, können Sie die folgenden Ressourcen aufrufen:

• Document Pool:
  http(s)://<DOMAIN>/signoSignUniversal/pool

• Showcase Demo:
  http(s)://<DOMAIN>/signoSignUniversal/documentation/showcase/index.html

• Swagger-UI:
  http(s)://<DOMAIN>/signoSignUniversal/documentation/swagger-ui.jsp

• Technische Dokumentation:
  http(s)://<DOMAIN>/signoSignUniversal/documentation/doc.xhtml

Troubleshooting

Sollte der Tomcat nicht starten, prüfen Sie bitte zunächst Folgendes:

• Wurde eine kompatible Java-Version verwendet?

• Wurde die JAVA_HOME Variable richtig konfiguriert?

• Wurde eine kompatible Tomcat-Version verwendet?

Sollte der Tomcat starten, aber ein Login in die Anwendung ist nicht möglich, gilt Folgendes zu prüfen:

• Wurde der Benutzer und die Rolle richtig konfiguriert?

• Hat der Tomcat-Dienst die benötigten Rechte, um die H2-Datenbank als Datei zu erstellen, bzw. wurde die externe Datenbank korrekt angebunden?