= openKonsequenz - How to run the module "gridFailureInformation@openK"

:Date: 2020-03-24
:Revision: 1

:icons:
:source-highlighter: highlightjs
:highlightjs-theme: solarized_dark

:imagesdir: ../img
:iconsdir: ../img/icons

:lang: en
:encoding: utf-8

<<<

IMPORTANT: Please be sure that you have first *Portal (Auth n Auth)* and *ContactBaseData* installed and configured!

== Requirements
* Browser (Chrome or Edge suggested)

== Prerequisites

* *To see this application running you have to run Portal and ContactBaseData application too.*
The reason is the authentication, which happened in the Portal login phase. Additionally
contacts that are used in the gridFailureInformation application are maintained in the
ContactBaseData module.

* A developing and administrating software for databases

** To work with a postgreSQL database is pgAdmin suggested

*** Download and install pgAdmin (version 4 is used during developing process) from:
        https://www.pgadmin.org/download/

*** Create a database

*** To initialize the database schema run the latest sql script:

 /src/resources/db/migration/V0_??__CREATE_GFI_DB.sql


== How to run the Backend
To run the backend you to create a separate directory for each backend microservice
you want to use, get the **.jar* file from the *target* directory of the java-project (which should exists after
a successful maven-build) and copy it to the new directory (i.e. "gfsBackService"). Y

=== Set up and start Apache Tomcat
Tomcat needs the Web Application Archive (war) file, which is produced by building the maven project, to run the application.

* Copy the *betriebstagebuch.war* file from the project file `/target` in the `<tomcat>/webapps` file. If there is a folder named *betriebstagebuch*, delete it before.
* Navigate to `C:\apache-tomcat-8.0.30\bin` and start Tomcat by clicking on *startup.bat*.
* Tomcat's default port is *8080*.

[source,text]
----
If 8080 port is already in use, you have to change tomcat's port as follows:
- Go to <tomcat>/conf folder
- Open server.xml file and search for "Connector port"
- Replace "8080" by your port number (for example 8181)
- Restart tomcat server (in the same folder which startup.bat is located, you can also find a shutdown.bat file).
----
{blank}

IMPORTANT: If you change the part number you have also adapt the port in the
frontend project: File "<PRJ_elogbookFE>/proxy.conf.json"

TIP: Look at the *http://87.128.212.254:8880/elogbookFE_ADoc/elogbook_interfaceDocumentation.html[elogbook_interfaceDocumentation]* for informations about the services.

== How to run the Frontend
To run the frontend project you need to have installed and updated Node.js and npm Angular-CLI.

=== Compile the Frontend

To compile say Angular-CLI to start.

* Open a command line and navigate to the root folder of the frontend project
* Run the command

[source,command]
----
   $  npm start
----
{blank}

* Open a browser and type:

[source,http]
----
    http://localhost:4200
----
{blank}

IMPORTANT: The reason you maybe don´t see the application running properly, is that you have not even logged in.
To do so, run first the Portal project, where you can log in and then open the elogbook.

== How to run the SIT-Web-Cache-Service
=== Prerequirements
* SIT-Web-Cache-Service is built properly. Otherwise following the instructions in the *howtoBuild* file!
* Your secured DMZ (demilitarized zone) can host the SIT-Web-Cache-Service.
* SIT-Web-Cache-Service needs *nodejs* and *nestjs*. Both have to be installed as described in the *howtoBuild* file.
* The SIT-Web-Cache-Service should be reachable from the SIT_BE. 

=== Run the service
* Copy all files from the build output to the provided folder in the DMZ.
* Open a command line and navigate to this folder. 
* Start the service with the following commands:
+
[source,command]
----
    $ node dist/main
----
{blank}

== How to run SIT-Web-FE (map- and table-component)
=== Prerequirements
* Both Parts of SIT-Web-FE are built properly. Otherwise following the instructions in the *howtoBuild* file!
* SIT-Web-Cache-Service runs properly. 
* Your secured DMZ (demilitarized zone) can host the SIT-Web-FE.
* SIT-Web-FE needs *nodejs* which have to be installed as descrbed in the *howtoBuild* file.
* The SIT-Web-FE should be able to consume the SIT-Web-Cache-Service and both parts should be in the same DMZ.
* If you do not have a web server in your environment (e.g. in a development environment) you can use *http-server*. To install this free and lightweight http server run the following command in a command line:
+ 
[source, command]
----
    $ npm install -g http-server
----

IMPORTANT: The description below use *http-server* as an http server. +
In many cases you will have your own web server - like *tomcat*, *apache*, *IIS* etc. - 
and you have to configure proxy settings and the http communication between all SIT components within this web server.

=== Run the map component
* Copy all files from the build output to the provided folder in the DMZ.
* Open a command line and navigate to this folder. 
* Start the service with the following commands:
+
[source,command]
----
    $ http-server dist/grid-failure-information-map-app/ -P http://localhost:3003 -p 3001
----
{blank}
+
CAUTION: Take care about this parameters: +
*-P*: The proxy for requesting the SIT-Web-Cache-Service. +
*-p*: TCP-Port of SIT-Web-FE

* Open a browser and open the address to your SIT-Web-FE with the correct TCP-Port:
+
[source,http]
----
    http://{SIT-Web-FE Adress}:3001
----
{blank}
+
=> A map with all grid failure appears in your browser.

=== Run the table component
* Copy all files from the build output to the provided folder in the DMZ.
* Open a command line and navigate to this folder. 
* Start the service with the following commands:
+
[source,command]
----
    $ http-server dist/grid-failure-information-table-app/ -P http://localhost:3003 -p 3002
----
{blank}
+
CAUTION: Take care about this parameters: +
*-P*: The proxy for requesting the SIT-Web-Cache-Service. +
*-p*: TCP-Port of SIT-Web-FE

* Open a browser and open the address to your SIT-Web-FE with the correct TCP-Port:
+
[source,http]
----
    http://{SIT-Web-FE Adress}:3002
----
{blank}
+
=> A table with all grid failure appears in your browser.

== How to use SIT-Web-FE

To show all grid failure on a map or in a table inside your own web application you can run SIT-Web-FE beside your application.

=== Prerequirements
* To have an secure access to the failure information you have to had installed the cache service as well.

=== Integrate the map component

* Copy all *.js* and *.css* files from the build output (_/dist/openk-grid-failure-information-map-init_) to your own web application folder. (Green boxes in the image below.)
* Reference all this files in your web application like the examples in the yellow boxes in the image below.
* Use the map app like an html element with the following tag: +
*<openk-grid-failure-information-map-init></openk-grid-failure-information-map-init>* +
(red box in the image)

.Neccessary files for map integration
[options="header"]
image::SIT_mapAppUsage.png[]

CAUTION: All builded files have an randomized alphanumerical postfix as you see in the image. This postfixes differs from build to build and have to be updated if a update occured.

=== Integrate the table component

The process to use the table component is similar to the description for the map component above. +
Note the following adjustments:

* You find the files to copy in the following folder: _/dist/openk-grid-failure-information-table-init_
* Use this html tag: + 
*<openk-grid-failure-information-table></openk-grid-failure-information-table>*