src/main/asciidoc/howto/howtoRun.adoc

= openKonsequenz - How to run the module "Contact Base Data"
:Date: 2020-02-28
:Revision: 1
:icons:
:source-highlighter: highlightjs
:highlightjs-theme: solarized_dark

<<<

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

== Requirements
* Browser (Chrome or Firefox)
* `contact-base-data.jar` file after a successfully maven build located in `<backend project root>/target`.
See `get_started.txt`.

== Prerequisites

* *To see this application running you have to run Portal application too.* The reason is the authentication, which happened in the Portal login phase.

== Configure Keycloak
Login into your Keycloak Admin Console and add the following Roles:

* kon-access
* kon-admin
* kon-reader
* kon-writer

* Option 1: Add/Edit users manually to/in Keycloak (see *Portal (Auth n Auth)* documents (not included here)) with the according roles.
* Option 2: You can also use the  `deploy/keycloak/addKeycloakUsersCDB.sh` script to add users. Adjust the script accordingly.
The script has to be copied and executed within the bin folder of the Keycloak installation `[keycloakRootFolder]/bin`.


== Install and configure Apache Tomcat
Tomcat is an open-source Java Servlet Container and provides a "pure Java" HTTP web server environment in which Java code can run.

* Download Tomcat version 8.x.xx from https://archive.apache.org/dist/tomcat/tomcat-8/
and extract it (apache-tomcat-8-x-xx.zip).
* Place the extracted folder on your C drive.


== Install and deploy the Database

Use any software for databases which is compatible to postgreSQL, we suggest pgAdmin 3:

. Download and install pgAdmin (version 3 is used during developing process) from:
        https://www.pgadmin.org/download/
. Create a database example: `ContactBaseDataDbProd`
. Create a Role with name `CBD_SERVICE` and a password. You can either use the script
in  `<backend project root>/deploy/db/01_createRole.sql` (edit the password beforehand) or do it manually with pgAdmin.
. Execute the sql script `<backend project root>/deploy/db/02_create_tables_with_example_data.sql`

The Database is now ready to use and filled with some example data. If you want to clean the example data execute the sql script
`<backend project root>/deploy/db/03_clean_example_data.sql`

== How to run the Backend

Put the `contact-base-data.jar` (see Requirements) in a folder of your choice.
Copy the file `application.yml` from `<backend project root>/src/main/resources/application.yml` next to your `contact-base-data.jar`.
Configure your copied `application.yml` according to your desired and mandatory settings. See next paragraph for an explanation of each
option.

=== Configuration of the Contact Base Data Backend

The backend service is configured with the `application.yml` file.

==== Profiles
This yml-file can be divided into different configuration profiles.
When starting the backend-service one has the possibility to specify
the active profile with the -D flag (more on that later).
If no active profile is selected the "Default" profile will be used.
The "Default" profile starts at the beginning of the file and ends at the first "---".
Profiles are divided by "---" and can be recognised by the keyword "spring: profiles: <profilename>".

If a profile is missing a setting, it'll be taken from the "Default" profile.

[source, txt]
----
[...]

---

spring:
profiles: test

[...]
----

==== Configuration Settings
All possible configuration values located in the in application.yml and their explanation.

* *spring*:
** *datasource*: Section for the database connection
*** url: jdbc:postgresql://serverdomain:port (default: 5432)/NameOfDatabase (Example: ContactBaseDataDbProd)
*** username: cbd_service
*** password: <password of cbd_service> see "Install and deploy the Database" point 3
** *flyway*:
*** *enabled*: (true or false) If enabled=true then the database migrations
will be performed automatically when starting the application
(this parameter should normally be set to "false")
** *ldap*:
*** *base*: The base LDAP path
*** *port*: The LDAP server port
*** *username*: Admin user of your LDAP
*** *password*: Admin password
*** *urls*: The URL of the LDAP server should be in the format ldap://myserver.example.com:10389.
For SSL access, use the ldaps protocol and the appropriate port, e.g. ldaps://myserver.example.com:636

* *ldap-sync*:
** *db-id-mapping*:
*** *telephone-number-id*: the primary ID for "telephone number" row in table REF_COMMUNICATION_TYPE.
(Default: 1) If set to -1 ldapmapping is disable for "telephone number"
*** *mail-id*: the primary ID for "mail" row in table REF_COMMUNICATION_TYPE.
(Default: 2) If set to -1 ldapmapping is disable for "mail"
** *scheduling*:
*** *enabled*: (true or false) Switches LDAP synchronisation on/off
*** *cron-expression*: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html[Cron Trigger Tutorial] +
Spring Cron only takes 5 parameters not 6, the year is exlcuded! +
Examples: '*/10 * * * * *' = every 10 seconds, '0 0 */3 ? * *' = every 3 hours, '0 0 0 * * ?' = every day at midnight.
** *attribute-mapping*:
*** [not changeable variable in contact base data modul]: [attribute field name in your LDAP to be mapped].All possible mappings are:
[source,yml]
----
uid: uid
fullname: cn
lastname: sn
firstname: givenname
title: title
mail: mail
department: department
telephone-number: phone
----

* *authnauth-sync*:
** *attribute-mapping*:
*** *lastname*:  (true or false) Switches AuthNAuth synchronisation of field Lastname on/off
*** *firstname*:  (true or false) Switches AuthNAuth synchronisation of field Firstname on/off
** *scheduling*:
*** *enabled*: (true or false) Switches AuthNAuth synchronisation on/off
*** *cron-expression*: http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html[Cron Trigger Tutorial] +
Spring Cron only takes 5 parameters not 6, the year is exlcuded! +
Examples: '*/10 * * * * *' = every 10 seconds, '0 0 */3 ? * *' = every 3 hours, '0 0 0 * * ?' = every day at midnight.
** *technical-username*: A technical user from the AuthNAuth modul doesn't have to be an admin
** *technical-userpassword*: Technical user password


* *server*:
** *port*: (Default: 9155) Port which is used for this backend server
** *max-http-header-size*: Maximum size for the http-headers

* *jwt*:
** *tokenHeader*: Name of the http-header which carries the authentication-token.
(should be "Authorization")
** *useStaticJwt*: If set to "true" then the backend will use *jwt.staticJwt*
as Authorization-token. (This won't work for calls to other modules
like the Auth'n'Auth-Modul, because the token will be out of date)
* *services*:
** *authNAuth*:
*** *name*: authNAuthService

* *authNAuthService*:
** *ribbon*:
*** *listOfServers*: Here one can configure the base
URL to the Auth'n'Auth-service Example: http://entopkon:8880.
The server where the Auth'n'Auth modul is installed.

* *feign*:
** *client*:
*** *config*:
**** *default*:
***** *connectTimeout*: (Default: 60000) Connection timeout for the REST-Calls (in ms).
***** *readTimeout*: (Default: 60000) Read timeout for the REST-Calls (in ms).

* *cors*:
** *corsEnabled*: (Default: false) (true or false) Cross-Origin Resource Sharing on/off

=== Starting the Backend

To execute the backend with the "Default" profile just run the command:

[source,command]
----
    $ java -jar ./contact-base-data.jar qserver
----
To execute the backend with for example the profile "qserver" run the command:

[source,command]
----
    $ java -Dspring.profiles.active=qserver -jar ./contact-base-data.jar qserver
----

IMPORTANT: Make sure you have set "corsEnabled" to true in your Production environment since
Frontend (Tomcat) and Backend (Spring Application) will run on different ports!

TIP: It's recommend to install the execution of the Backend as a System Service (Win/Linux).

== How to run the Frontend

=== Configure your Webserver
Frontend (Tomcat) and Backend (Spring Application) will run on different ports you need to configure
your webserver to proxy the request coming form the Frontend to the Backend.
The following is an example configuration for an Apache HTTP Server (Webserver) for port 80.

[source,conf]
----

<VirtualHost *:80>

        # Kontaktstammdaten
        ProxyPass /contactdatabase/api http://localhost:9155

</VirtualHost>

----

`http://localhost:9155` is the location of the Backend. The port has to be adjusted according to your settings made in
see section "How to run the Backend" -> "Configuration of the Contact Base Data Backend" -> "Configuration Settings" -> "Server:" "Port:"


=== Deploying the Frontend

. Create a folder named `contactdatabase` in `<tomcat>/webapps` folder
. After building the Frontend (see `howtoBuild` file) copy the content of the `dist` folder to `<tomcat>/webapps/contactdatabase`
. Configure the Frontend, see "Configuration Settings" below.
. Start your Tomcat

Now log in with the "Portal Application" and open the "Contact Base Data" module. If it shows the overview and the its example data
the application was successfully deployed.

==== Configuration Settings
Open <tomcat>/webapps/contactdatabase/config/env.json

[source, json]
----
{"env":"production"}
----

Here you can set which of the configuration files residing in <tomcat>/webapps/contactdatabase/config/*
will be used. If set to "production" like above, the *production.json* will be used.

To enable the redirect to the Login (Portal) Page open the configuration file (e.g.: *production.json*) and set the variable "portalLoginUrl" pointing to your Portal Login.

[source, json]
----
...
"paths": {
"imagesRoot": "/assets/images/",
"userImageFolder": "/assets/images/users/",
"portalLoginUrl": "http://localhost:8880/portalFE/#/login"
},
...
----


If the variable "portalLoginUrl" is not set or missing the default "Logout Page" will be shown.