﻿////
******************************************************************************
* Copyright © 2017-2018 PTA GmbH.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
*
*     http://www.eclipse.org/legal/epl-v10.html
*
******************************************************************************
////
= [ WIRD AUF KSM ANGEPASST NACH RÜCKSPRACHE IM Kontaktstammdaten: Sprint Review (26.02.2020) ] openKonsequenz - How to deploy the module "eLogbook@openK"
Simon Reis <simon.reis@pta.de>
:Date: 2020-02-25
:Revision: 2
:icons:
:source-highlighter: highlightjs
:highlightjs-theme: solarized_dark

<<<

== Deployment

The elogbook application consists of 3 parts regarding the deployment.

. Frontend: "elogbookFE"-Directory
. Backend: "elogbook.war"
. Database: The scripts are found in the "db" folder within the backend sources.

=== Deployment of the application components

==== Deployment of the frontend

The Frontend SPA is built as a folder, that contains all the required files for
the application. If you have built the frontend yourself then the content of the "dist"-folder
within the Frontend development-directory has to be copied into the target-directory of the apache-tomcat.
If you got the Frontend delivered in form of a archive (elogbookFE.zip) put *its content* into the
target-directory "elogbookFE" of the apache-tomcat:

 <Apache-Tomcat>/webapps/elogbookFE

If the target folder does not exist, it has to be created manually.

==== Deployment of the backend
The backend REST-services are built in form of a "WAR"-file (to be found
in the "target"-directory of the MAVEN-directory structure or delivered to you).
For deployment, this file has to be copied to the directory

 <Apache-Tomcat>/webapps

==== Deployment of the database
Currently there is no automatic mechanism for distributing structural
or content related changes to the database.
DB related changes are deployed using database scripts directly in suitable
DB management applications like *pgAdminIII* or directly in the *postgres-console*.
These script can be found in the backend project in the directory

 <elogbook backend project directory>/db/postgreSQL


. If needed, create the Database and the access role "btbservice" with *"01_add_DB.sql"*
. The script *"01a_drop_DB_1.0.0.sql"* is only needed for dropping all objects in the db!
. Use the script *"02_create_DB_1.0.0.sql"* to create all database objects
. You will probably need to modify the last script *"03_config_DB_1.0.0.sql"* before you run it. Configurate
your branches, grid territories and your responsibilities here!

TIP: If you want to install the system on an oracle dbms, please take the db scripts from
the */db/oracle* subfolder.

==== Configuration of the system

===== DB based configuration

. Grid territories - The grid-territories have to be configured in the DB-Table *ref_grid_territory*

Please modify the "03_config_DB_*.sql" script (in "<elogbook backend project dir>\db\postgreSQL" ) to change the
configuration. (This file is contained in the *oracle* folder as well.

===== Configuration of the webserver

There exists the file *context.xml* in the "conf" subdirectory (*<TOMCAT>/conf*) of the target apache tomcat installation.
Add the following parameter and resource in order to access the correct backend configuration and to
gain access to the database:

.context.xml
[source,xml]
----
[...]
    <!-- Uncomment this to disable session persistence across Tomcat restarts -->

    <!--Manager pathname=""/>

    <Parameter name="environment" override="false" value="Development"/-->

    <Parameter name="OK_ELOGBOOK_ENVIRONMENT" override="false" value="Production"/>

    <Resource name="jdbc/okBetriebstagebuchDS"
              auth="Container"
              type="javax.sql.DataSource"
              driverClassName="org.postgresql.Driver"
              url="jdbc:postgresql://{dbserver}:5432/{dbname}"
              username="{dbuser}"
              password="{dbpassword}"/>


    <!-- Uncomment this to enable Comet connection tacking (provides events
         on session expiration as well as webapp lifecycle) -->
[...]
----

For oracle please use...

.contextOracle.xml
[source,xml]
----
[...]
    <!-- Uncomment this to disable session persistence across Tomcat restarts -->

    <!--Manager pathname=""/>


    <Parameter name="environment" override="false" value="Development"/-->

    <!-- Parameter for different Backend configs  -->
    <Parameter name="OK_ELOGBOOK_ENVIRONMENT" override="false" value="Production"/>

    <Resource name="jdbc/okBetriebstagebuchDSO"
              auth="Container"
              type="javax.sql.DataSource"
              driverClassName="oracle.jdbc.driver.OracleDriver"
              url="jdbc:oracle:thin:@{orasvr}:1521:{dbname}"
              username="{dbuser}"
              password="{dbpassword}"/>


    <!-- Uncomment this to enable Comet connection tacking (provides events
         on session expiration as well as webapp lifecycle) -->
[...]
----

*{dbserver}*, *{dbname}*, *{dbuser}* and *{dbpassword}* need to be replaced by the actual values.

CAUTION: The postgres database drivers (postgresql-42.0.0.jar or ojdbc7_g.jar} referenced in the *context.xml* needs to be copied from the lib folder within the
backend source files to the *<TOMCAT>/lib* folder of the target tomcat installation.

(The jar is located in *deploy/lib/*)

CAUTION: If you want to use an oracle db then you have to change
the file backendConfigProduction: Set "activePersistencyUnit" to "betriebstagebuchORA".
(see next chapter "Configuration of the backend").


===== Configuration of the backend

After the backend war file has been deployed and unpacked inside of the *<TOMCAT>/webapps* folder there are different
 backend config files to be found in the folder *<TOMCAT>/webapps/elogbook/WEB-INF/classes*

* backendConfigCustom.json
* backendConfigDevLocal.json
* backendConfigDevServer.json
* backendConfigProduction.json

The active configuration is chosen by parameter *OK_ELOGBOOK_ENVIRONMENT* (see context.xml above).
Possible values are:

* *Custom* (for backendConfigCustom.json)
* *DevLocal* (for backendConfigDevLocal.json)
* *DevServer* (for backendConfigDevServer.json)
* *Production* (for backendConfigProduction.json)

After choosing an environment the corresponding json file has to be configured:

.backendConfigXXX.json
[source,json]
----
{
  "portalBaseURL" : "http://{hostname}:{port}/portal/rest/beservice",
  "fileRowToRead": "9",
  "importFilesFolderPath": "/home/btbservice/importFiles",
  "activePersistencyUnit": "betriebstagebuch",
  "applicationAccessRole": "elogbook-access"
}
----
* *portalBaseURL* - The portal base url should point the the address where the portal backend (the *Auth&Auth*-Server)
                    can be accessed. This is important for the authorization of the backend services.
* *fileRowToRead* - Defines the line number inside the import-file of the relevant text line.
* *importFilesFolderPath* - Defines the exchange directory for the import functionality
* *activePersistencyUnit* - Defines the active part of the file persistenc.xml. Choose *"betriebstagebuchORA"* for the
                    usage of OracleDB and *"betriebstagebuch"* to use PostgreSQL.
* *applicationAccessRole* - Defines the role for which users are fetched (For the selection in shift-change-dialog).


== Design Decisions

All architecture decisions based on the Architecture Committee Handbook. There are no deviations.

== Risks and Technical Debts

(Currently there aren't any known issues)

<<<