Vorwort

Wir möchten Sie herzlich als Kunden des AMANA Tax Portal und DAC 6 willkommen heißen.

Im Folgenden geben wir eine Anleitung zur erstmaligen Installation des Portals auf einem Tomcat-Applikationsserver. Falls sich Ihre Anforderungen für die Installation von den hier gemachten Annahmen unterscheiden, beraten wir Sie gern, um Ihnen die Integration des Portals in Ihrem Unternehmen zu erleichtern.

Prüfung der Vorbedingungen

Infrastruktur

Bitte prüfen Sie mit Hilfe des Dokuments Systemanforderungen, ob die bei Ihnen gegebene Infrastruktur aktuell ist. Sollte dies nicht der Fall sein, passen Sie die Infrastruktur bitte an, bevor Sie mit der Portal-Installation beginnen.

Installation der Datenbank

Die Schritte zur Einrichtung sind an dieser Stelle allgemein gehalten, um den unterschiedlichen Konfigurationen der Datenbanksysteme gerecht zu werden.
Erstellen Sie zwei neue Datenbank/Datenbankschemata auf dem Datenbankserver. Eins für das AMANA Tax Portal, das zweite für das DAC 6 Modul.
Erstellen Sie einen Datenbankbenutzer mit Berechtigung zum „INSERT“, „UPDATE“, „DELETE“, „ALTER“, „CREATE“ auf diese Datenbank.
1. Unter SQL Server benötigt der Anwender die Datenbankrollen db_datareader, db_datawriter und ein Rolle zur Ausführung von Stored Procedures, z.B.: db_executor:
  CREATE ROLE db_executor
  GO
  GRANT EXECUTE TO db_executor
  GO
Stellen Sie sicher, dass sich der Applikationsserver mit diesem Benutzer zur Datenbank verbinden kann.
Bitte stellen sie sicher, dass ein aktuelles JDBC-Treiberpaket, passend zu ihrem DBMS und der eingesetzten Java-Version, im Lib-Verzeichnis des Tomcats befindet.
Zur Aktualisierung des Datenbankschemas stehen zwei Varianten zur Verfügung:
1. Automatisch
  Über die integrierte Datenbankmigration (siehe Konfiguration des "Tomcat 8.5" Punkt 2b)
2. Manuell
  Manuelle Einspielung der im Installationspaket enthaltenen Datenbankskripte
Bitte klären Sie im Vorfeld, welche Variante Sie bei Ihnen eingesetzt werden soll.
Führen Sie die in Ihrer Auslieferung enthaltenen Skripte zur Erstellung der Datenbank auf dieser aus.
Achten Sie darauf, dass der User, der die DB-Skripte einspielt, alle Rechte auf der Datenbank des Portals und DAC6 hat.

Installation des Web Application Servers

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 1) und 2) beschriebenen Installationsvorgang.

Wir empfehlen für den Betrieb von Portal und DAC 6 die Verwendung von zwei separaten Applikationsservern.

Hierbei müssen Sie sicherstellen, dass die Applikationsserver unterschiedliche Portnummern nutzen.

Dies ist bei der Installation konfigurierbar.

Installation des JDK

Installieren Sie ein passendes JDK und erstellen die Systemvariable „JAVA_HOME“, die auf das Installationsverzeichnis zeigt.

Installation des "Tomcat 8.5"

Installieren Sie Apache Tomcat 8.5 in ein Verzeichnis Ihrer Wahl. Im weiteren Verlauf wird das Verzeichnis „C:\Server\Tomcat“ angenommen.

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

Konfiguration des "Tomcat 8.5" nach der Installation

Führen Sie nach der Installation die Datei "tomcat8w.exe" im bin Verzeichnis des Tomcats aus.
Führen Sie folgende Schritte durch:
1. Tab „General“: Stellen Sie den Start des Dienstes auf automatisch.
2. Falls Sie die automatische Datenbankmigration aus den Applikationen nutzen wollen, fügen Sie bitte zusätzlich folgende Parameter im Feld "Java Options" ein:
  1. "-Dportal.db.migration=auto" für das Portal
  2. "-Ddac6.db.migration=auto" für DAC 6
3. Wenn Sie den TransferService von AMANA für die automatische Übertragung der Meldung an die Finanzverwaltung nutzen möchten, ist ein zusätzlicher Parameter notwendig.
  Dieser Parameter aktiviert den regelmäßigen Abruf der Verarbeitungsprotokolle.
  1. -Ddac6.scheduler.autostart=true
    
    Der Parameter ist bei einem Setup mit mehreren Tomcats und einem Load Balancer nur bei einem Tomcat vorzunehmen, da beim Abruf ansonsten konkurrierende Zugriffe und Fehler auftreten können.
4. Tab „Java“: Im Feld "Initial Memory Pool" tragen Sie "512" ein
5. Tab „Java“: Im Feld "Maximum Memory Pool" tragen Sie ca. die Hälfte des verfügbaren physikalischen Arbeitsspeichers ein. Als Minimum empfehlen wir jedoch "2048". Bedenken Sie bitte bei 32-Bit-Systemen die Beschränkung des Arbeitsspeichers auf ca. 3,5 GB. Die hier gemachten Speichereinstellungen beeinflussen die Performance und Lauffähigkeit der Applikation. Unter Umständen sind diese bei wachsender Benutzung im Laufe der Zeit anzupassen.
Kopieren Sie den zu Ihrem Datenbankserver passenden Datenbanktreiber in das "\lib"-Verzeichnis im Tomcat-Installationsverzeichnis.
1. Microsoft SQL Server - https://docs.microsoft.com/en-us/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server
2. Oracle - https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html
3. MySQL - https://dev.mysql.com/downloads/connector/j/
Die Datenbankverbindung ist als JNDI-Verbindung im Tomcat zu konfigurieren:
1. Öffnen Sie die "context.xml"-Datei im "\conf"-Verzeichnis des Tomcats
2. Fügen Sie einen neuen "Resource" XML Tag mit passenden Attributen für Ihr eingesetztes DBMS und folgenden Namen ein:
  1. "jdbc/portaldatasource" für das Portal
  2. "jdbc/dac6datasource" für DAC 6
3. "Resource" XML Tag Beispiel für DAC6 mit MSSQL
```
<Resource name="jdbc/dac6datasource" auth="Container" type="javax.sql.DataSource"
               maxTotal="100" maxIdle="30" maxWaitMillis="10000"
               username="dac6" password="dac6" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
               url="jdbc:sqlserver://localhost:1433;databaseName=dac6" />
```
Optional für Microsoft SQL Server: Konfiguration für Windows-Authentifizierung
1. Aus dem JDBC Treiber Paket muss zusätzlich aus dem Ordner auth die passende dll in das System32 Verzeichnis des Systems kopiert werden.
  Beispiel-Pfad: .\sqljdbc_8.2.2.0_deu\sqljdbc_8.2\deu\auth\x64\mssql-jdbc_auth-8.2.2.x64.dll
2. Der Windows Benutzer muss im Tomcat eingetragen werden
  1. Der Benutzer benötigt Berechtigungen auf dem Server des Tomcats zum Ausführen des Tomcat-Dienstes sowie Schreibberechtigungen im Tomcatordner für Logs
  2. Der Benutzer benötigt Berechtigungen auf dem Server der Datenbank
  3. Der Benutzer benötigt o.g. Berechtigungen auf dem Datenbankschema
3. Die Verbindungen in der context.xml müssen diesem Beispiel entsprechen:
```
<Resource name="jdbc/dac6datasource" type="javax.sql.DataSource"
                        maxTotal="100" maxIdle="30" maxWaitMillis="10000
						driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
						url="jdbc:sqlserver://[SERVER-NAME];DatabaseName=[DATABASE_NAME];Integratedsecurity=true"/>
```

Einrichtung der Deployments

Die folgenden Schritte richten die Webapplikationen Portal und DAC 6 auf dem "Tomcat 8.5"-Applikationsserver ein.

Kopieren und entpacken Sie die war-Dateien aus dem Auslieferungspaket in das „\webapps“-Verzeichnis im Tomcat-Installationsverzeichnis. Sie können das Paket selbstverständlich zunächst an einen anderen Ort editieren, um dort die Konfiguration vorzunehmen, und nach Fertigstellung nach „\webapps“ kopieren.
Nun konfigurieren Sie folgende Dateien unterhalb dieses Ordners:
1. Portal und DAC 6 - "\WEB_INF\classes\META-INF\persistence.xml":
  1. Bei Verwendung einer JNDI-Verbindung
    1. Keine Anpassung in der "persistence.xml"-Datei notwendig
  2. Bei direkte Angabe der Datenbankverbindung
    1. Löschen Sie die Zeile mit dem XML Tag "<non-jta-data-source>" vollständig
    2. Kommentiern Sie den "<properties>" XML Block ein
    3. Kommentieren Sie den Block für Ihr eingesetztes DBMS ein und die anderen Blöcke aus
    4. Passen Sie IP/Hostname des Datenbankservers, den Datenbanknamen und Benutzer/Passwort entsprechend den unter dem Punkt „Datenbank“ gewählten Parametern an.
2. DAC 6 - "\WEB-INF\classes\sql\common\V20200113100000000__Insert_TSETTING.sql":
  1. Ändern Sie die URL zum Wert "OPENID_PORTAL_PATH"
  2. Hier muss die URL angegeben werden, unter der das Portal in Ihrem Netzwerk öffentlich erreichbar ist.
    1. Z.B. "http://demo.amana.de/portal"
  3. Ändern Sie die URL zum Wert "OPENID_DAC6_PATH"
  4. Hier muss die URL angegeben werden, unter der das DAC 6 in Ihrem Netzwerk öffentlich erreichbar ist.
    1. Z.B. "http://demo.amana.de:8080/dac6"
  5. Nur so kann sichergestellt werden, dass sich DAC 6 ordnungsgemäß beim Portal registrieren kann und letztendlich die Weiterleitung funktioniert.
3. DAC 6 - "\WEB-INF\classes\sql\common\V20200515000000000__Insert_TSETTING.sql":
  1. Ändern Sie die URL zum Wert "API_PORTAL_PATH"
  2. Hier muss die URL angegeben werden, unter der das Portal in Ihrem privaten Netzwerk erreichbar ist.
    1. Z.B. "http://servername/portal"
  3. Ändern Sie die URL zum Wert "API_DAC6_PATH"
  4. Hier muss die URL angegeben werden, unter der das DAC 6 in Ihrem privaten Netzwerk erreichbar ist.
    1. Z.B. "http://servername:8080/dac6"
  5. Nur so kann sichergestellt werden, dass DAC 6 und das Portal untereinander kommunizieren können.

Start und Aktivierung

Starten Sie nun den Tomcat Applikationsserver, auf dem Sie das Portal installiert haben, entweder unter den Systemdiensten oder mit der „Configure Tomcat“ Applikation.
Warten Sie bis der Server gestartet wurde.
Öffnen Sie einen unterstützten Browser und geben folgendes in die Adressleiste ein (beachten Sie den bei der Installation des Tomcats gewählten Port): "http://<IP-Adresse oder Hostname der Applikationsservers>:<Portnummer des Applikationsservers>/portal"
Es sollte nun eine Login-Seite laden, dort können Sie sich – Benutzer: superuser ; Passwort: test – einloggen und ihr Passwort ändern.
Navigieren Sie zum Dialog "Aktivierung".
Kopieren Sie den von uns per E-Mail an Sie versandten Aktivierungsschlüssel in das Eingabefeld "Schlüssel" und klicken Sie auf "Aktivierung hinzufügen".
In der Tabelle sollte nun das aktivierte Modul "DAC6" aufgelistet sein.
Starten Sie nun den Tomcat Applikationsserver, auf dem Sie das DAC 6 installiert haben, entweder unter den Systemdiensten oder mit der „Configure Tomcat“ Applikation.
Prüfen Sie, ob im Portal-Applikationsmenüs der Eintrag DAC 6 dargestellt wird und das Modul im Bereich Module mit den korrekten URL-Pfaden angezeigt wird.
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.
Überprüfen Sie abschließend die Inhalte der Log-Dateien "portal_system.log" und "portal_dbmigration.log" sowie "dac6_system" und "dac6_dbmigration.log" auf ERROR-Meldungen. Nehmen Sie bei Auffälligkeiten bitte ebenfalls Kontakt mit uns auf.

Manuelle Modulregistrierung

Nach Absprache mit AMANA kann es sein, dass die Registrierung des DAC 6 Moduls im Portal manuell erfolgen soll. In diesem Fall führen Sie bitte folgende Schritte durch:

Java Option im DAC 6 Tomcat
1. Stoppen falls notwendig den DAC 6 Tomcat
2. Fügen Sie bitte zusätzlich folgenden Parameter im Feld "Java Options" ein: "-Ddac6.manual.registration=true"
DAC 6 Modul im Portal eintragen
1. Navigieren Sie im Portal zu Administration → Module
2. Klicken Sie auf "Anlegen"
3. Wählen Sie unter "Modulname" den Eintrag "DAC 6" aus
4. Tragen Sie unter "Root URL" die DAC 6 Root URL ein (z.B.: "http://servername:8080/dac6")
5. Tragen Sie unter "Login URL" die DAC 6 Login URL ein. In der Regel ist dies die Root URL + "/login" (z.B.: "http://servername:8080/dac6/login")
6. Tragen Sie unter "Api URL" die URL zur API vom DAC 6 ein. In der Regel ist dies die Root URL + "/portal-api" (z.B.: "http://servername:8080/dac6/portal-api")
7. Klicken Sie auf "Speichern"
8. Kopieren Sie den neuen Wert unter "Client ID" zum Zwischenspeichern in einen beliebigen Texteditor
9. Kopieren Sie den neuen Wert unter "Secret" zum Zwischenspeichern in denselben Texteditor
10. Klicken Sie auf "Zurück"
"Client ID" und "Secret" in der Datenbank eintragen
1. Öffnen Sie ihre Datenbankmanagement-Applikation und stellen Sie eine Verbindung zur DAC 6 Datenbank her
2. Ersetzten Sie in folgendem Datenbankstatement den Ausdruck ${ClientId} durch die zwischengespeicherte "Client ID" und führen es gegen die DAC 6 Datenbank aus:
```
INSERT INTO TSETTING (SETTINGKEY, SETTINGVALUE, SETTINGTYPE) VALUES('OPENID_CLIENTID', '${ClientId}', 2);
```
3. Ersetzten Sie in folgendem Datenbankstatement den Ausdruck ${Secret} durch das zwischengespeicherte "Secret" und führen es gegen die DAC 6 Datenbank aus:
```
INSERT INTO TSETTING (SETTINGKEY, SETTINGVALUE, SETTINGTYPE) VALUES('OPENID_CLIENTSECRET', '${Secret}', 2);
```
DAC 6 Tomcat wieder starten

Abschließende Bemerkungen

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 ständig gesichert werden. Hier reicht es, den Stand bei Auslieferung einer Version bereitzuhalten.