KON-678 Umzug der Dokumentation auf Eclipse Doc-Repository

.gitignore

+HELP.md
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**
+!**/src/test/**
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### Logs ###
+/logs
+
+### Sonar ###
+/.scannerwork
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+*.log
+*.gz
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+
+### VS Code ###
+.vscode/

get_started.txt

+ *******************************************************************************
+ * Copyright (c) 2020 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************
+
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+GET STARTED
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+**********************************************************************
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! *
+PLEASE BE SURE THAT YOU HAVE FIRST PORTAL INSTALLED AND CONFIGURED ! *
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! *
+**********************************************************************
+
+Here you find a step-by-step instruction on how to build all documentation in this repository including:
+- architectureDocumentation.adoc
+- howtoBuild.adoc
+- howtoConfigure.adoc
+- howtoRun.adoc
+- userDocumentation.adoc
+At the end you have a pdf and a html version of each adoc (documentation).
+
+---------------- REQUIREMENTS -------------
+* Java 1.8
+* Apache Maven 3.6.1
+* Graphviz
+
+If you meet this requirements, check if you have set JAVA_HOME and M2_HOME.
+    - If yes: Ignore step 1,2 and 3
+    - If no: Follow the corresponding steps below
+
+
+-------------------- 1 ---------------------
+Install java 8
+
+- Open a cmd and check your java version
+    $ java -version
+- If you dont have java version 1.8 then download and install it from:
+        http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
+- Set JAVA_HOME (Windows OS):
+    Right click on This Computer and select Properties.
+    On the Advanced tab, select Environment Variables, and then edit JAVA_HOME to point to where the JDK software is located, for example, C:\Program Files\Java\jdk1.8.xxx.
+    Also, edit The Path variable in System variables and add the bin path (C:\Program Files\Java\jdk1.8.xxx\bin)
+- Restart your PC
+- Confirm by checking the version
+    $ java -version
+
+
+-------------------- 2 ---------------------
+Install Apache Maven to your pc
+
+Maven is a tool that can be used for building and managing any Java-based project.
+
+- Download maven 3.6.1 from
+        https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.6.1/
+- Extract the folder and place it on your C drive
+- Set M2_HOME (Windows OS):
+    - Right click on This Computer and select Properties.
+    - On the Advanced tab, select Environment Variables, and then create M2_HOME to point to where the Maven software is located, for example, C:\apache-maven-3.5.0.
+    - Also edit The Path variable in System variables and add the bin path (C:\apache-maven-3.5.0\bin)
+- Restart your PC
+- Confirm with
+    $ mvn -v
+
+-------------------- 3 ---------------------
+Install Graphviz
+Graphviz is open source graph visualization software. You need this software because of auto-generated graphics in the documentations.
+
+* Download and install Graphviz from https://www.graphviz.org/download/
+* If not already done, set the PATH variable
+
+ Value of variable: <GRAPHVIZ_DIR>\bin
+
+-------------------- 4 ---------------------
+Building the documentation:
+- Open a command line and navigate to the root folder of this project (same location of this very get_started.txt file)
+- Use the following call to cleanly build and install artifacts:
+    $ mvn clean install
+
+-------------------- 5 ---------------------
+If you successfully build the maven project you can find in /target/generated-docs all the documentations of this projects
+in pdf and html form, choose according to your liking:
+    - "howtoBuild" -> here you can read how to build the whole (backend and frontend) project
+    - "howtoConfigure" -> here you can read how to configure the Application
+    - "howtoRun" -> here you can read how to run/start the Application
+    - "architectureDocumentation" -> here you can read about the architecture pf this module
+
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+NEXT STEP -> READ THE howtoBuild FILE             !
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
\ No newline at end of file

pom.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    *******************************************************************************
+    * Copyright (c) 2019 Contributors to the Eclipse Foundation
+    *
+    * See the NOTICE file(s) distributed with this work for additional
+    * information regarding copyright ownership.
+    *
+    * This program and the accompanying materials are made available under the
+    * terms of the Eclipse Public License v. 2.0 which is available at
+    * http://www.eclipse.org/legal/epl-2.0.
+    *
+    * SPDX-License-Identifier: EPL-2.0
+    *******************************************************************************
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.eclipse.openk</groupId>
+    <artifactId>contact-base-data.documentation</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+    <name>contact-base-data-documentation</name>
+    <description>Contact Base Data project for openKONSEQUENZ</description>
+
+    <properties>
+        <skip.asciidoc>false</skip.asciidoc>
+        <java.version>1.8</java.version>
+        <asciidoctor-maven-plugin-version>1.5.3</asciidoctor-maven-plugin-version>
+        <asciidoctorj-pdf-version>1.5.0-alpha.11</asciidoctorj-pdf-version>
+        <asciidoctorj-version>1.5.4</asciidoctorj-version>
+        <asciidoctorj-diagram-versions>1.5.4.1</asciidoctorj-diagram-versions>
+        <jacoco-maven-plugin.version>0.8.5</jacoco-maven-plugin.version>
+        <jruby-complete-version>9.0.0.0</jruby-complete-version>
+        <maven.compiler.target>1.8</maven.compiler.target>
+        <maven.compiler.source>1.8</maven.compiler.source>
+    </properties>
+
+    <dependencies>
+
+    </dependencies>
+
+    <dependencyManagement>
+
+    </dependencyManagement>
+
+    <build>
+        <finalName>${project.artifactId}</finalName>
+        <plugins>
+            <plugin>
+                <groupId>org.asciidoctor</groupId>
+                <artifactId>asciidoctor-maven-plugin</artifactId>
+                <version>${asciidoctor-maven-plugin-version}</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.jruby</groupId>
+                        <artifactId>jruby-complete</artifactId>
+                        <version>${jruby-complete-version}</version>
+                    </dependency>
+                    <dependency>
+                        <groupId>org.asciidoctor</groupId>
+                        <artifactId>asciidoctorj-pdf</artifactId>
+                        <version>${asciidoctorj-pdf-version}</version>
+                    </dependency>
+                    <dependency>
+                        <groupId>org.asciidoctor</groupId>
+                        <artifactId>asciidoctorj</artifactId>
+                        <version>${asciidoctorj-version}</version>
+                    </dependency>
+                    <dependency>
+                        <groupId>org.asciidoctor</groupId>
+                        <artifactId>asciidoctorj-diagram</artifactId>
+                        <version>${asciidoctorj-diagram-versions}</version>
+                    </dependency>
+                </dependencies>
+                <configuration>
+                    <sourceDirectory>src/main/asciidoc</sourceDirectory>
+                    <requires>
+                        <require>asciidoctor-diagram</require>
+                    </requires>
+                    <attributes>
+						<imagesoutdir>${project.build.directory}/generated-docs/images</imagesoutdir>
+						<imagesDir>${project.build.directory}/generated-docs/images</imagesDir>
+                    </attributes>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>output-html</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                        <configuration>
+                            <skip>${skip.asciidoc}</skip>
+							<imagesDir>./images</imagesDir>
+                            <requires>
+                                <require>asciidoctor-diagram</require>
+                            </requires>
+                            <sourceHighlighter>coderay</sourceHighlighter>
+                            <backend>html</backend>
+                            <doctype>book</doctype>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>output-pdf</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                        <configuration>
+                            <skip>${skip.asciidoc}</skip>
+							<imagesDir>${project.build.directory}/generated-docs/images</imagesDir>
+                            <requires>
+                                <require>asciidoctor-diagram</require>
+                            </requires>
+                            <sourceHighlighter>coderay</sourceHighlighter>
+                            <backend>pdf</backend>
+                            <doctype>book</doctype>
+                            <attributes>
+                                <icons>font</icons>
+                                <pagenums />
+                                <toc />
+                                <idprefix />
+                                <idseparator>-</idseparator>
+                            </attributes>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+
+        </plugins>
+    </build>
+
+
+</project>
\ No newline at end of file

src/main/asciidoc/howto/howtoBuild.adoc

+= openKonsequenz - How to build 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
+* Node.js 12.14.1
+* Angular-CLI
+
+== How to build the Backend
+How to build the Backend is described in `/deploy/`*get_started.txt*. Since you are reading this file you have most likely already
+have build the backend succesfully.
+
+== How to build the Frontend
+
+=== Install Node.js
+
+Node.js is an open-source, cross-platform JavaScript run-time environment for executing JavaScript (also Typescript which is a strongly typed form of JavaScript) code server-side.
+
+* Download Node.js 12.14.1 from https://nodejs.org/download/release/v12.14.1/ by clicking on a xxx.msi image for windows.
+* Run the downloaded Node.js .msi Installer - including accepting the license, selecting the destination, and authenticating for the install.
+This requires Administrator privileges, and you may need to authenticate
+* To ensure Node.js has been installed, run the following in your terminal - you should get something like v12.14.1
+
+[source,command]
+----
+    $ node -v
+----
+{blank}
+
+=== Update the npm Angular-CLI client
+This package manager comes bundled with Node.js and its good to have the latest version.
+
+* Open a command line and navigate to the root folder of the frontend project
+* Run the following commands (the version is defined in the package.json file):
+
+[source,command]
+----
+    $ npm install --save-dev @angular/cli
+----
+{blank}
+
+[source,command]
+----
+    $ npm install
+----
+{blank}
+
+=== Building the Frontend
+
+* Open a command line and navigate to the root folder of the frontend project
+* Run the following commands:
+
+[source,command]
+----
+    $ npm run build
+----
+{blank}
+
+
+TIP: Next Step -> Read the *howtoRun* file!
+
+
+

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`
+. 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.
+
+