Vorbedingungen

JDBC Treiber für eine der folgenden Datenbanken:

Oracle: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/ (Die Treiberversion muss zur Datenbankversion passen. Aktuell vom Deployment mitgelieferter Treiber: ojdbc8 - 12.2.0.1)
Microsoft SQL Server: http://msdn.microsoft.com/data/jdbc/ (Die Treiberversion muss zur Datenbankversion passen. Aktuell vom Deployment mitgelieferter Treiber: mssql-jdbc - 8.2.0.jre8))

Bereitstellung seitens Amana:

In Ihrer Auslieferung sollten Sie nach dem Entpacken der bereitgestellten ZIP-Datei folgende Ordnerstruktur vorfinden:

databasescript → alle deployment → war-Datei mit der aktuellen Applikation

(optional) databasescript → alle notwendigen Update-Skripte für die Datenbank
deployment → war-Datei mit der aktuellen Applikationdie Datenbank (wird nur noch im Sonderfall benötigt, Standardmäßig wird die Datenbank automatisch initialisiert und aktuallisiert)

Installation Apache Tomcat Server

1. Wir gehen im Folgenden von einer Installation auf einem Windows Betriebssystem aus. Eine Installation auf einem Unix-artigen System unterscheidet sich lediglich in den Pfaden und dem unter 2. und 3. beschriebenen Installationsvorgang.
2. Installieren Sie die empfohlene JAVA-Version und erstellen Sie entweder die Systemvariable „JAVA_HOME“, die auf das Installationsverzeichnis zeigt oder setzen in den Startskripten des Tomcats den JavaHome Pfad. Deaktivieren Sie bitte unbedingt die automatischen Java-Updates.
3. Installieren Sie den Apache Tomcat Server in ein Verzeichnis Ihrer Wahl (Hinweis: zu tiefe Unterordnerstrukturen können zu Problemen mit Pfadlängen führen). Im weiteren Verlauf wird das Verzeichnis „C:\Server\Tomcat“ angenommen. Dazu im Einzelnen:

• Wir empfehlen, die Startmenüeinträge mit zu installieren, um die Konfiguration zu vereinfachen.
• Die Ports, welche der Tomcat verwendet, können nach Ihren Anforderungen angepasst werden.

Konfiguration des Tomcat Servers:

Anchor
TomcatConfig TomcatConfig

1. Führen Sie nach der Installation die Applikation ->Startmenü->Tomcat->“configure tomcat“ aus.
2. Führen Sie folgende Schritte durch:
   -
   1. Im Fenster „General“: Stellen Sie den Start des Dienstes auf automatisch.
   - Im
   1. Im Fenster Initial Memory Pool tragen Sie „128“ ein.
   - Im
   1. Im Fenster Maximum Memory Pool tragen Sie ca. die Hälfte des verfügbaren physikalischen Arbeitsspeichers ein.
   
   
   1. Bedenken Sie bitte bei 32 Bit Systemen die Beschränkung des Arbeitsspeichers auf ca. 3.5 GB. Die hier konfigurierten Speichereinstellungen beeinflussen die Performance und Lauffähigkeit der Applikation.
   
   -
   1. Unter Umständen sind diese bei wachsender Benutzung im Laufe der Zeit anzupassen.
   In der web.xml im conf-Verzeichnis
   1. Im Fenster "Java" im Feld "Java 9 Options" den Eintrag ""--add-opens=java.base/java.util=ALL-UNNAMED" hinzufügen.
   2. Ggf. die Server Kodierung manuell auf UTF-8 setzen. Dafür kann der Parameter -Dfile.encoding=UTF-8 im Fenster "Java" im Feld "Java Options" gesetzt werden.

   1. In der web.xml im conf-Verzeichnis des Tomcat Servers (%TOMCAT_HOME%/conf) muss in der servlet-Section mit dem Namen <servlet-name>jsp</servlet-name> ein <init-param> Block mit Parameter „mappedfile“ = false ergänzt werden.

      Code Block
      language xml title web.xml
      <servlet> <servlet-name>jsp</servlet-name> <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> <init-param> <param-name>fork</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>xpoweredBy</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>mappedfile</param-name> <param-value>false</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet>

      
      

   2. In der context.xml des Tomcat Servers sollte folgende Anpassung vorgenommen werden:

      Wir empfehlen das Attribut cacheMaxSize des Elements Resources auf 100000 Kilobytes (100MB) zu erhöhen:

      Code Block
      language xml title context.xml
      <WatchedResource>WEB-INF/web.xml</WatchedResource> <Resources cachingAllowed="true" cacheMaxSize="100000" />

      
      

   3. Kopieren Sie das Deployment (i.d.R "vat.war") aus dem deployment-Ordner Ihrer Auslieferung in das „webapps“ Verzeichnis im Tomcat Installationsverzeichnis.

   Einrichtung Datenbank

   Die Schritte zur Einrichtung sind an dieser Stelle allgemein gehalten, um den unterschiedlichen Konfigurationen der Datenbanksysteme gerecht zu werden.

   1. Erstellen Sie eine neue Datenbank/Datenbankschema auf dem Datenbankserver.
   2. Erstellen Sie einen Datenbankbenutzer mit Berechtigung für "CREATE", "INSERT", "UPDATE", "DELETE", "ALTER" auf dieser Datenbank. (Bei Oracle: CONNECT + RESSOURCE).
   3. Hinweis Oracle: Ab Oracle 12 muss der Oracle-Benutzer Quotas auf (s)einem Tablespace erhalten, z.B.:

      
      ALTER USER amanavat QUOTA 1000M ON users;

      ALTER USER amanavat QUOTA UNLIMITED ON amanavat;
      
      
   4. Stellen Sie sicher, dass vom Applikationsserver aus mit diesem Benutzer auf die Datenbank zugegriffen werden kann.
   5. (optional) Führen Sie die in Ihrer Auslieferung enthaltenen Skripte zur Erstellung der Datentabellen aus.
      Achten Sie darauf, dass dem User, der die DB-Skripte einspielt, die notwendigen Rechte zur Erstellung der Tabellenstruktur zur Verfügung stehen.
      Sollte es wider Erwarten zu Fehlermeldungen bei Ausführung der Skripte kommen, kontaktieren Sie bitte unseren Support und schicken uns das Ausführungsprotokoll zu.
   Variante

   
   

   Note
   Durch automatische SQL-Skripte, die beim Serverstart ausgeführt werden, ist ein händischen einspielen der Skripte in der Regel nicht notwendig.

   Variante 1: Konfiguration JNDI (Datasource) Datenbankverbindung mit Benutzer/Passwort

   Anchor
   Datenbank1 Datenbank1

   Kopieren Sie bitte den passenden JDBC Treiber in das lib-Verszeichnis des Apache Tomcat Servers (%TOMCAT_HOME%/lib).

   In der context.xml des Apache Tomcat Servers muss innerhalb des <Context> Blockes ein passender Resource-Eintrag für die Datenbankverbindung angelegt werden:

   Beispiel Datasource Eintrag für MSSQL:

   Code Block
   language xml title MSSQL Datasource linenumbers true
   <Resource name="jdbc/gtcvatdatasource" auth="Container" type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME]" username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

   Beispiel Datasource Eintrag für Oracle:

   Code Block
   language xml title Oracle Datasource linenumbers true
   <Resource name="jdbc/gtcvatdatasource" auth="Container" type="javax.sql.DataSource" driverClassName="oracle.jdbc.driver.OracleDriver" url="jdbc:oracle:thin:@[SERVER-ADRESS]:[PORT]:[INSTANCE]" username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

   Im Datasource Eintrag passen Sie bitte die SERVER-ADRESSE des Datenbankservers, den Datenbanknamen und Benutzer/Passwort entsprechend Ihrer aufgesetzten Datenbank an.

   Variante 2: Konfiguration JNDI (Datasource) Datenbankverbindung mit Windows-User

   Anchor
   Datenbank2 Datenbank2

   Kopieren Sie bitte den passenden JDBC Treiber in das lib-Verszeichnis des Apache Tomcat Servers (%TOMCAT_HOME%/lib).

   Die Datenbankverbindung in der context.xml des Tomcat-Servers kann alternativ über den Windows-User in dessen Kontext der Tomcat läuft aufgebaut werden. Dazu sind folgende Schritte durchzuführen:

   1. Microsoft SSPI Treiber herunterladen (sqljdbc 7.0): https://www.microsoft.com/de-de/download/sqljdbc_7.0

      Info
      Wichtig hierbei ist verwendete JAVA Version: Bei einem 64-bit JAVA wird x64-Version des Treibers benötigt, bei einem 32-bittigen Java entsprechend die x86-Version.

      
      

   2. Der Treiber wird in einer selbstentpackenden EXE geliefert, die bspw. per 7-Zip entpackt werden kann oder alternativ kann der Treiber als tar.gz-Archiv heruntergeladen werden.

   3. Kopieren Sie die sqljdbc_auth.dll aus dem Unterordner "/auth" in das "\windows\system32" Verzeichnis ihrer Windowsinstallation.

      
      
   4. Kopieren Sie aus dem Unterordner des Treibers "/jre8" die Datei sqljdbc42 in das "/bin"-Verzeichnis ihrer installierten JAVA-Version (die vom Tomcat verwendet wird).
      
      
      
      

   5. In der context.xml des Tomcat-Servers muss ein passender Datasource-Eintrag für die Datenbankverbindung konfiguriert werden:

      Code Block
      language xml title MSSQL Datasource linenumbers true
      <Resource name="jdbc/gtcvatdatasource" type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" url="jdbc:sqlserver://[SERVER-NAME]\SQLEXPRESS;DatabaseName=[DATABASE_NAME];Integratedsecurity=SSPI" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

      
      

   6. Zudem muss der Windows-User in den "Tomcat Properties" eingetragen werden - siehe Abbildung:

      Info
      Bitte beachten, dass der Benutzer auch die Berechtigung hat sich als „Dienst“ anzumelden, sonst startet der Tomcat nicht mehr.

      

   Systemstart und Aktivierung

   1. Starten Sie nun den Tomcat Applikationsserver entweder unter den Systemdiensten oder mit der „Configure Tomcat“ Applikation.
   2. Starten Sie einen Browser und geben in die Adressleiste ein (beachten Sie den bei „Installation Tomcat“ gewählten Port):
      http://<IP-Adresse oder Hostname des Applikationsservers>:[Port]/vat
   3. Es sollte nun eine Login-Seite laden, dort können Sie sich mit
      Benutzer: superuser
      Passwort: test
      einloggen.
   4. Nun sollte eine Webseite Sie zur Aktivierung auffordern. Kopieren Sie den Inhalt des oberen Textfensters in eine E-Mail und schicken Sie ihn an Ihren Ansprechpartner aus unserem Haus. Alternativ können Sie den Button „Aktivierung anfordern“ klicken, der eine E-Mail automatisch erstellt.
   5. Wir senden Ihnen die Aktivierung in Form einer Textdatei zu. Dessen Inhalt kopieren Sie bitte in das untere Textfenster und bestätigen durch Klick auf „Aktivieren“.
   6. Sollte bei einem der vorherigen Punkte ein Fehler auftreten, prüfen Sie bitte die unter Einrichtung der Applikation eingetragenen Parameter und nehmen Kontakt mit uns auf.

   Abschließende Bemerkungen

   Nach erfolgter Aktivierung des VAT@GTC ist die Installation erfolgreich abgeschlossen. Die Software kann nun den Fachabteilungen zur Benutzung oder fachlichen Tests übergeben werden.

   Zum Abschluss noch einige Anmerkungen:

   • Wir möchten empfehlen, eine regelmäßige Sicherung der Datenbank durchzuführen, da diese die Daten der Applikation enthält.
   • Das Deployment muss nicht kontinuierlich gesichert werden. Hier reicht es, den Stand bei Auslieferung einer Version bereitzuhalten.
   • Die durchgeführte Konfiguration sollten Sie dokumentieren, damit Anpassungen im Falle von Aktualisierungen des Systems oder einer Wiederherstellung nachvollzogen werden können. Insbesondere Anpassungen, die abweichend von diesem Dokument vorgenommen wurden, sind zu dokumentieren.

Preconditions

JDBC driver for one of the following databases:

Oracle: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/ (The driver version must match the database version. Current driver provided by the deployment: ojdbc5 - 11.2.0.3.0)
Microsoft SQL Server: http://msdn.microsoft.com/data/jdbc/ (The driver version must match the database version. Current driver provided by the deployment: mssql-jdbc - 6.2.2.jre8)

Provided by Amana:

You should find the following folder structure in your distribution after unpacking the provided ZIP file:

databasescript → all necessary update scripts for the database
deployment → war-file with the current application

Installation of the Apache Tomcat Server

1. In the following we assume an installation on a Windows operating system. An installation on a Unix-like system differs only in the paths and the installation procedure described under 2. and 3.
2. Install the recommended JAVA version and either create the system variable "JAVA_HOME" which points to the installation directory or set the JavaHome path in the Tomcat start scripts. Be sure to disable the automatic Java updates.
3. Install the Apache Tomcat Server into a directory of your choice (Please note: too deep subdirectory structures can lead to path length problems). In the following the directory "C:\Server\Tomcat" is assumed. This is explained in detail:

• We recommend to install the start menu entries to simplify the configuration.
• The ports used by Tomcat can be customized to your needs.

Configuration of the Tomcat Server:

In the web.xml in the conf directory of the Tomcat server (%TOMCAT_HOME%/conf) a <init-param> block with parameter "mappedfile" = false must be added in the servlet with name <servlet-name>jsp</servlet-name> section.

<servlet>        
		<servlet-name>jsp</servlet-name>
        <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
        <init-param>
            <param-name>fork</param-name>
            <param-value>false</param-value>
        </init-param>
        <init-param>
            <param-name>xpoweredBy</param-name>
            <param-value>false</param-value>
        </init-param>
        <init-param>
             <param-name>mappedfile</param-name>
             <param-value>false</param-value>
        </init-param> 
        <load-on-startup>3</load-on-startup>
    </servlet>

We recommend increasing the cacheMaxSize attribute of the Resources element to 100000 kilobytes (100MB):

<WatchedResource>WEB-INF/web.xml</WatchedResource>
<Resources cachingAllowed="true" cacheMaxSize="100000" />

Setting up the Database

The steps for setting up the database are kept general at this point in order to do justice to the different configurations of the database systems.

Variant 1: Configuration of JNDI (Datasource) database connection with user/password

Please copy the appropriate JDBC driver into the lib directory of the Apache Tomcat server (%TOMCAT_HOME%/lib).

In the context.xml of the Apache Tomcat Server a corresponding resource entry for the database connection must be created within the <Context> block:

Example Datasource entry for MSSQL:

 <Resource name="jdbc/gtcvatdatasource" auth="Container"
 	type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
    url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME]"
    username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
    maxWaitMillis="-1"/>

Example Datasource entry for Oracle:

 <Resource name="jdbc/gtcvatdatasource" auth="Container"
 	type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver"
    url="jdbc:oracle:thin:@[SERVER-ADRESS]:[PORT]:[INSTANCE]"
    username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
    maxWaitMillis="-1"/>

Please adjust the SERVER-ADRESS of the database server, the database name and the user/password in the Datasource entry according to your database.

Variant 2: Configuration of JNDI (Datasource) database connection with Windows user

Please copy the appropriate JDBC driver into the lib directory of the Apache Tomcat server (%TOMCAT_HOME%/lib).

The database connection in the context.xml of the Tomcat server can alternatively be established via the Windows user in whose context the Tomcat is running. The following steps have to be performed:

Download Microsoft SSPI driver (sqljdbc 7.0): https://www.microsoft.com/de-de/download/sqljdbc_7.0

Info
The used JAVA version is important: A 64-bit JAVA requires the x64 version of the driver, a 32-bit Java requires the x86 version.

The driver is delivered in a self-extracting EXE, which can be unpacked e.g. by 7-Zip or alternatively the driver can be downloaded as tar.gz archive.

1. Copy the sqljdbc_auth.dll from the subdirectory "/auth" into the "\windows\system32" directory of your Windows installation.
   Image Removed
2. Copy the file sqljdbc42 from the subdirectory of the driver "/jre8" into the "/bin" directory of your installed JAVA version (which is used by Tomcat).
   Image Removed
   Image Removed

   In the context.xml of the Tomcat server a corresponding datasource entry must be configured for the database connection:

   Code Block
   language xml title MSSQL Datasource linenumbers true
   <Resource name="jdbc/gtcvatdatasource" type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" url="jdbc:sqlserver://[SERVER-NAME]\SQLEXPRESS;DatabaseName=[DATABASE_NAME];Integratedsecurity=SSPI" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

   In addition, the Windows user must be entered in the "Tomcat Properties" - see illustration:

   Info
   Please note that the user also has the right to log in as a "service", otherwise Tomcat will not start anymore.

   Image Removed

TLS-Verbindung zum SQL-Server einrichten

Anchor
Datenbank3 Datenbank3

Ab der Treiberversion 10.x von mssql-jdbc (Microsoft SQL-Server) muss eine Verbindung ohne TLS explizit konfiguriert werden, ansonsten geht der Treiber von einer TLS-Verbindung aus und erwartet dafür vorgesehen Zertifikate.

Um diese zu deaktivieren, muss die context.xml des Tomcat-Servers wie folgt erweitert werden:

 <Resource name="jdbc/gtcvatdatasource" auth="Container"
 	type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
    url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME];encrypt=false;trustServerCertificate=true"
    username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
    maxWaitMillis="-1"/>

Entscheidend sind encrypt=false und trustServerCertificate=true in der url.

Wenn die TLS-Verbindung verwendet werden soll, dann werden folgende Informationen benötigt:

 <Resource name="jdbc/gtcvatdatasource" auth="Container"
 	type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
    url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME];hostNameInCertificate=[HOST_NAME_IN_CERTIFICATE];trustStore=[TRUSTSTORE_LOCATION];trustStorePassword=[TRUSTSTORE_PASSWORD]
    username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
    maxWaitMillis="-1"/>

Der SQL-Server muss mit einen Zertifikat abgesichert sein und dieses muss sich in einem TrustStore/KeyStore befinden. Sowohl der Pfade zum TrustStore als auch das Passwort werden mitgegeben und zusätzlich der HostName im Zertifikat.

Informationen zu den Parametern:

https://docs.microsoft.com/de-de/sql/connect/jdbc/setting-the-connection-properties?view=sql-server-ver16

Informationen zum Konfigurieren:

https://docs.microsoft.com/de-de/sql/database-engine/configure-windows/manage-certificates?view=sql-server-ver16

https://docs.microsoft.com/de-de/sql/connect/jdbc/connecting-with-ssl-encryption?view=sql-server-ver16

https://docs.microsoft.com/de-de/sql/connect/jdbc/configuring-the-client-for-ssl-encryption?view=sql-server-ver16

Systemstart und Aktivierung

1. Starten Sie nun den Tomcat Applikationsserver entweder unter den Systemdiensten oder mit der „Configure Tomcat“ Applikation.
2. Starten Sie einen Browser und geben in die Adressleiste ein (beachten Sie den bei „Installation Tomcat“ gewählten Port):
   http://<IP-Adresse oder Hostname des Applikationsservers>:[Port]/vat
3. Es sollte nun eine Login-Seite laden, dort können Sie sich mit
   Benutzer: superuser
   Passwort: test
   einloggen.
4. Nun sollte eine Webseite Sie zur Aktivierung auffordern. Schicken Sie eine E-Mail an Ihren Ansprechpartner aus unserem Haus. 
5. Wir senden Ihnen die Aktivierung in Form einer Textdatei zu. Dessen Inhalt kopieren Sie bitte in das untere Textfenster und bestätigen durch Klick auf „Aktivieren“.
6. Sollte bei einem der vorherigen Punkte ein Fehler auftreten, prüfen Sie bitte die unter Einrichtung der Applikation eingetragenen Parameter und nehmen Kontakt mit uns auf.

Abschließende Bemerkungen

Nach erfolgter Aktivierung des VAT@GTC ist die Installation erfolgreich abgeschlossen. Die Software kann nun den Fachabteilungen zur Benutzung oder fachlichen Tests übergeben werden.

Zum Abschluss noch einige Anmerkungen:

• Wir möchten empfehlen, eine regelmäßige Sicherung der Datenbank durchzuführen, da diese die Daten der Applikation enthält.
• Das Deployment muss nicht kontinuierlich gesichert werden. Hier reicht es, den Stand bei Auslieferung einer Version bereitzuhalten.
• Die durchgeführte Konfiguration sollten Sie dokumentieren, damit Anpassungen im Falle von Aktualisierungen des Systems oder einer Wiederherstellung nachvollzogen werden können. Insbesondere Anpassungen, die abweichend von diesem Dokument vorgenommen wurden, sind zu dokumentieren.