Documentation of REMReM generate in OpenSource (#155)

README.md

@@ -27,9 +27,17 @@ Eiffel REMReM Generate takes a partial message in JSON format, validates it and
 
 # Documentation
 
-1. [**Running RemRem-Generate service**]()
-    - [**Run in Docker**](wiki/markdown/docker.md)
+1. [**Introduction**](wiki/markdown/index.md)
 
+2. [**Pre-requisites**](wiki/markdown/index.md#Pre-requisites)
+
+3. [**Installation**](wiki/markdown/installation.md)
+
+4. [**Run in Docker**](wiki/markdown/docker.md)
+
+5. [**Usage**](wiki/markdown/usage.md)
+
+6. [**Logging**](wiki/markdown/logging.md)
 
 # About this repository
 The contents of this repository are licensed under the [Apache License 2.0](./LICENSE).

wiki/markdown/index.md

@@ -0,0 +1,18 @@
+## Introduction
+
+REMReM (**REST Mailbox for Registered Messages**) is a set of tools that can be used to generate validated Eiffel messages and publish them on a RabbitMQ message bus. They can be run as micro services or as stand-alone CLI versions. For more details on the micro services and the REMReM design, see [Eiffel REMReM](https://github.com/eiffel-community/eiffel-remrem)
+
+Eiffel REMReM Generate takes a partial message in JSON format, validates it and adds mandatory fields before outputting a complete, valid Eiffel message.
+
+
+## Pre-requisites
+
+*   JDK 8
+*   Tomcat 8
+
+For supporting latest features, Eiffel REMReM Generate should use the latest version of [Eiffel REMReM Semantics](https://github.com/eiffel-community/eiffel-remrem-semantics).
+
+## Components
+
+*   REMReM Generate CLI (Command Line Interface)
+*   REMReM Generate Service

wiki/markdown/installation.md

@@ -0,0 +1,12 @@
+# Installation
+Eiffel REMReM Generate is maven project and can be built by executing following command:
+
+```
+mvn clean install
+```
+
+Binary is released via [jitPack](https://jitpack.io/#eiffel-community/eiffel-remrem-generate)
+
+The latest REMReM Generate CLI binary can be downloaded via [generate-cli.jar](https://jitpack.io/#eiffel-community/eiffel-remrem-generate)
+
+The latest REMReM Generate Service binary can be downloaded via [generate-service.war](https://jitpack.io/#eiffel-community/eiffel-remrem-generate)

wiki/markdown/logging.md

@@ -0,0 +1,14 @@
+## Logging
+
+REMReM Generate application logging is implemented using the logback-classic. It requires user to configure the logback.xml file.  
+When used without logback.xml log messages will look as below:
+
+```
+  %PARSER_ERROR[wEx]%PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr]
+       %PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr]
+```
+To configure the logback.xml file use **-Dlogging.config=path/logback.xml**
+
+To get info about logback configurations see [here](https://logback.qos.ch/manual/configuration.html).
+
+To get sample logback.xml to use see [here](https://eiffel-community.github.io/eiffel-remrem-generate/logback/logback-sample.xml).

wiki/markdown/usage.md

@@ -0,0 +1,7 @@
+## Usage
+
+To get information about configuration and usage of **REMReM Generate CLI** see [here](../markdown/usage/generate-cli.md).
+
+To get information about configuration and usage of **REMReM Generate Service** see [here](../markdown/usage/service.md).
+
+Examples used here in the Eiffel events can be found in the protocol repository. Please follow [eiffel syntax](https://github.com/eiffel-community/eiffel/tree/master/eiffel-syntax-and-usage) and [eiffel vocabulary](https://github.com/eiffel-community/eiffel/tree/master/eiffel-vocabulary).

wiki/markdown/usage/configuration.md

@@ -0,0 +1,159 @@
+## Configuration
+
+#### Running and configuring RemRem-Generate without Tomcat installation
+
+It is also possible to execute RemRem-Generate without external Tomcat installation and using the embedded tomcat in Spring application instead.
+
+If RemRem-Generate is executed without external Tomcat installation, the configuration should be based on Spring application properties, see service/src/main/resources/application.properties file for available properties.
+
+If running with java command, example:
+
+```
+java -jar service/target/generate-service-x.x.x.war --properties.parameter1=value --properties.parameter2=value --properties.parameter3=value ......
+```
+
+It is also possible to provide path to the spring properties file:
+
+```
+java -jar service/target/generate-service-x.x.x.war --spring.config.location=path/to/applicattion.propeties
+```
+
+Second option to execute RemRem-Generate is to execute maven commands from the source code root folder, example:
+
+```
+mvn spring-boot:run -Dspring-boot.run.arguments=--properties.parameter1=value,--properties.parameter2=value,--properties.parameter3=value,--properties.parameter4=value ......
+```
+
+When using maven command, Spring properties can also be changed by editing service/src/main/resources/application.properties file.
+
+#### Running and configuring in Tomcat
+
+Eiffel REMReM Service **generate-service.war** file should be deployed in Tomcat Server. For doing this, generate-service.war file should deployed in directory: _tomcat/webapps_.
+
+Configuration is done in Tomcat using a config.properties file: _tomcat/conf/config.properties_.
+
+**NOTE:** in each example assuming the generate-service.war is deployed in tomcat as **generate**.
+
+**NOTE:** for other than eiffelsemantics protocol, provide the Java opts as:
+
+```
+set JAVA_OPTS="-Djava.ext.dirs=/path/to/jars/" in catalina.sh
+```
+
+**NOTE:** in the above example, protocol jar file must be present inside "/path/to/jars/" folder.
+
+**NOTE:** "-Djava.ext.dirs" is no longer working in some JAVA8 versions and in JAVA9. So users should create a wrapper project to include both Generate/Publish and their protocol in or place the protocol library in the folder for external dependencies of their JVM installation.
+
+### Jasypt configurations
+
+Jasypt Spring Boot provides Encryption support for property sources(passwords, secret info ..etc) in Spring Boot Applications. To support this functionality in our application we need to add the following property in property file
+
+**jasypt.encryptor.password: The key value which was used while encrypting the original password**
+
+The above encryptor password must be same for both encryption and decryption of the original password(ldap,rabbitmq...etc)  
+The encryptor password will be used by jasypt-spring-boot library in application to decrypt the encrypted password at runtime.
+
+#### How to encrypt the password:
+
+```
+1) Download the jasypt jar file from any of the below locations
+[Link to Jasypt](http://www.jasypt.org/download.html) (or) [Link to Maven](https://mvnrepository.com/artifact/org.jasypt/jasypt/1.9.2)
+
+2) Execute the below command to generate Jasypt encrypted password
+    java -cp jasypt-1.9.2.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI input="any password" password=any intermediate key
+
+input   : any password which we want to encrypt(Ex: rabbitmq password, ldap user password, etc...)
+password: A Jasypt key used to encrypt the above input( The Jasypt key can be anything, but make sure same key to be used for decryption)
+
+Example:
+    Run the below command in Command line
+
+    java -cp jasypt-1.9.2.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI input="dummyPassword" password=dummy
+
+output:
+    ----ENVIRONMENT-----------------
+
+    Runtime: Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 25.144-b01
+
+    ----ARGUMENTS-------------------
+
+    algorithm: PBEWithMD5AndDES
+    input: dummyPassword
+    password: dummy
+
+    ----OUTPUT----------------------
+
+    euJcvto7NtCDiWT7BKFW0A==
+```
+
+Use the above encrypted password in your property file like this **ENC(encrypted password)**
+
+ **Ex:rabbitmq.password: ENC(euJcvto7NtCDiWT7BKFW0A ==)**
+
+**Note: REMReM will work without jasypt encryption also but if you have encrypted any text using jasypt library then** _jasypt.encryptor.password_ **property should be present in property file**
+
+### Ldap authentication configurations
+
+ Active Directory authentication can be enabled for the REMReM REST service by setting the configuration property 
+
+   **activedirectory.generate.enabled:true**.
+
+**NOTE:** it is recommended to disable ldap authentication for REMReM Publish Service for correct work of REMReM Publish Service endpoint 
+
+   **/generateAndPublish.**
+
+```   
+activedirectory.generate.enabled: <true | false>
+activedirectory.ldapUrl:          <LDAP server url>
+activedirectory.managerPassword:  <LDAP server manager password>
+activedirectory.managerDn:        <LDAP managerDn pattern>
+activedirectory.rootDn:           <LDAP rootDn pattern>
+activedirectory.userSearchFilter: <LDAP userSearchFilter pattern>
+```
+
+ **LDAP authentication without Base64 encryption of user details::**
+
+```
+ $ curl -XPOST -H "Content-Type: application/json" --user username:password --data @ActivityCanceled.json http://localhost:8080/generate-service/eiffelsemantics?msgType=eiffelactivitycanceled
+```
+
+ **NOTE:** each HTTP request must then include an Authorization header with value 
+
+      **Basic <Base64 encoded username:password>**
+      
+**LDAP authentication with Base64 encryption of user details::**
+
+```
+$ curl -XPOST -H "Content-Type: application/json" -H 'Authorization: Basic cGFzc3dvcmQ=' --data @ActivityCanceled.json http://localhost:8080/generate-service/eiffelsemantics?msgType=eiffelactivitycanceled
+```
+
+### Event Repository Lookup Configurations
+
+ER lookup configurations define whether to enable querying towards Event Repository or not. ER lookup configurations are enabled by configuring below property in configuration file.
+
+```
+ event-repository.enabled : <true | false>
+```
+
+**NOTE:** Allowed value for _event-repository.enabled_ is _true/false_.If the value is not one of this the service will be terminated.
+
+If _event-repository.enabled_ is false then REMReM Generate will not Lookup ER data. Refer below snippet for instance,
+
+```
+            event-repository.enabled : false
+            event-repository.url     : http(s)://<host>:<port>/<context-path>
+```
+
+If _event-repository.enabled_ is true then Event Repository URL should be mandatory.
+
+```
+            event-repository.enabled : true
+            event-repository.url     : http(s)://<host>:<port>/<context-path>
+```
+
+**NOTE:** If Lookup configurations are enabled and EventRepository URL is not provided then the remrem service gets terminated.
+
+```
+            event-repository.enabled : true
+            event-repository.url     :
+```