Added configuration documentation. (#239)

tobiasake · web-flow · commit cf579551b109 · 2019-08-14T09:04:09.000+02:00
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
@@ -24,10 +24,12 @@ ei.backend.instances.list.json.content=
 #ei.backend.instances.list.json.content=[{ "contextPath": "", "port": "8090", "name": "EI-Backend-1", "host": "localhost", "https": false, "defaultBackend": true}]
 
 ###### EI Documentation Link Url ##########
-ei.eiffel.documentation.urls={ "EI Frontend GitHub": "https://github.com/eiffel-community/eiffel-intelligence-frontend",\
-                               "EI Backend GitHub": "https://github.com/eiffel-community/eiffel-intelligence",\
+ei.eiffel.documentation.urls={ "EI front-end documentation": "https://eiffel-community.github.io/eiffel-intelligence-frontend",\
+                               "EI front-end GitHub": "https://github.com/eiffel-community/eiffel-intelligence-frontend",\
+                               "EI back-end documentation": "https://eiffel-community.github.io/eiffel-intelligence",\
+                               "EI back-end GitHub": "https://github.com/eiffel-community/eiffel-intelligence",\
                                "Eiffel Github main page": "https://github.com/eiffel-community/eiffel",\
-                               "Test Rules User Guide": "https://github.com/eiffel-community/eiffel-intelligence-frontend/blob/master/wiki/markdown/test-rules.md" }
+                               "User guide for test rules page": "https://github.com/eiffel-community/eiffel-intelligence-frontend/blob/master/wiki/markdown/test-rules.md" }
 
 #### LOGGING #########
 logging.level.root: INFO
diff --git a/wiki/markdown/configuration.md b/wiki/markdown/configuration.md
@@ -0,0 +1,64 @@
+# Configuration
+
+To be able to execute and use Eiffel-Intelligence front-end, some configuration need to provided.
+All configurations is made via application.properties file. These properties can also be provided as Java properties arguments as well.
+
+## Eiffel-Intelligence back-end
+
+Eiffel-Intelligence front-end is dependent that at least one EI back-end instance is up and running.
+It is possible to configure several EI Backend instances.
+
+EI back-end instances is configured by setting **ei.backend.instances.list.json.content** property, example:
+
+    ei.backend.instances.list.json.content=[{ "contextPath": "", "port": "8090", "name": "EI-Backend-1", "host": "ei-backend-host-1", "https": false, "defaultBackend": true},\
+                                            { "contextPath": "", "port": "8090", "name": "EI-Backend-2", "host": "ei-backend-host-2", "https": false, "defaultBackend": false},\
+                                            { "contextPath": "", "port": "8090", "name": "EI-Backend-3", "host": "ei-backend-host-3", "https": false, "defaultBackend": false},\
+                                            { "contextPath": "", "port": "8090", "name": "EI-Backend-4", "host": "ei-backend-host-4", "https": false, "defaultBackend": false}]
+
+You can set as many EI back-end instances as you intend to use.
+
+## Eiffel-Intelligence front-end server settings
+
+Which port EIffel-Intelligence front-end web-server should be started with is set by the property **server.port**:
+
+    server.port=8080
+
+**ei.frontend.service.host** property is the hostname on the host where EI front-end application is started on.
+
+**ei.frontend.service.port** property is the port number on the host where EI front-end application is started on.
+
+**ei.frontend.context.path** property is used when EI front-end application is started with a context path in web-server.
+
+If running locally with "mvn spring-boot:run" no context-path is added which means you can leave the **ei.frontend.context.path** property empty.
+
+    ei.frontend.service.host=localhost
+    ei.frontend.service.port=${server.port}
+    ei.frontend.context.path=
+
+## HTTPS security
+
+If Eiffel-Intelligence front-end need to be executed with secure HTTPS connections, then these properties need to be set:
+
+    ei.use.secure.http.frontend=false
+    server.ssl.key-store: <keystore.p12>
+    server.ssl.key-store-password: <mypassword>
+    server.ssl.key-store-type: <PKCS12>
+    server.ssl.key-alias: <tomcat>
+
+Read more in Spring documentation about how to enable HTTPS security in Spring applications.
+
+## Customize documentation links
+
+It is possible to add and change Documentation url links that is seen in the Eiffel-Intelligence front-end Web-UI.
+Documentaiton url links is configured by property **ei.eiffel.documentation.urls**, example:
+
+    ei.eiffel.documentation.urls={ "EI front-end documentation": "https://eiffel-community.github.io/eiffel-intelligence-frontend",\
+                               "EI front-end GitHub": "https://github.com/eiffel-community/eiffel-intelligence-frontend",\
+                               "EI back-end documentation": "https://eiffel-community.github.io/eiffel-intelligence",\
+                               "EI back-end GitHub": "https://github.com/eiffel-community/eiffel-intelligence",\
+                               "Eiffel Github main page": "https://github.com/eiffel-community/eiffel",\
+                               "User guide for test rules page": "https://github.com/eiffel-community/eiffel-intelligence-frontend/blob/master/wiki/markdown/test-rules.md" }
+
+## Other properties
+
+All Eiffel-Intelligence front-end properties can be found in [application.properties](https://github.com/Ericsson/eiffel-intelligence-frontend/blob/master/src/main/resources/application.properties) example file.
diff --git a/wiki/markdown/docker.md b/wiki/markdown/docker.md
@@ -18,24 +18,23 @@ With the Docker image user can try-out the Eiffel-Intelligence front-end on a Do
 
 ## Follow these step to build the Docker image.
 
-1. Build the Eiffel-Intelligence front-end war file:
-
-`mvn package -DskipTests`
+ **1**  Build the Eiffel-Intelligence front-end war file:
+    
+    mvn package -DskipTests
 
 
 This will produce a war file in the "target" folder.
 
-2. Build the Docker image with the war file that was produced from previous step:
-
-`docker build -t eiffel-intelligence-frontend:0.0.19 --build-arg URL=./target/eiffel-intelligence-frontend-0.0.19.war -f src/main/docker/Dockerfile .`
+**2** Build the Docker image with the war file that was produced from previous step:
+    
+    docker build -t eiffel-intelligence-frontend:0.0.19 --build-arg URL=./target/eiffel-intelligence-frontend-0.0.19.war -f src/main/docker/Dockerfile .
 
 Now docker image has build with tag "eiffel-intelligence-frontend:0.0.19"
 
 ## Run Docker image on local Docker Host
 To run the produced docker image on the local Docker host, execute this command:
-
-
-`docker run -p 8071:8080 --expose 8080 -e server.port=8080 -e logging.level.log.level.root=DEBUG -e logging.level.org.springframework.web=DEBUG -e logging.level.com.ericsson.ei=DEBUG eiffel-intelligence-frontend:0.0.19`
+    
+    docker run -p 8071:8080 --expose 8080 -e server.port=8080 -e logging.level.log.level.root=DEBUG -e logging.level.org.springframework.web=DEBUG -e logging.level.com.ericsson.ei=DEBUG eiffel-intelligence-frontend:0.0.19
 
 # Some info of all flags to this command
 
@@ -73,17 +72,19 @@ In web-browser use url with docker host ip number: "\<docker host ip\>:8071/"
 Switch-back-end functionality do not work when "localhost" address is used.
 
 Another option to configure Eiffel Intelligence front-end is to provide the application properties file into the container, which can be made in two ways:
-1. Put application.properties file in Tomcat Catalina config folder in container and run Eiffel Intelligence front-end:
-
-`docker run -p 8070:8080 --expose 8080 --volume /path/to/application.properties:/usr/local/tomcat/config/application.properties eiffel-intelligence-frontend:0.0.19`
 
-2. Put application.properties file in a different folder in container and tell EI where the application.properties is located in the container:
+**1** Put application.properties file in Tomcat Catalina config folder in container and run Eiffel Intelligence front-end:
+    
+    docker run -p 8070:8080 --expose 8080 --volume /path/to/application.properties:/usr/local/tomcat/config/application.properties eiffel-intelligence-frontend:0.0.19
 
-`docker run -p 8070:8080 --expose 8080 --volume /path/to/application.properties:/tmp/application.properties -e spring.config.location=/tmp/application.properties eiffel-intelligence-frontend:0.0.19`
+**2** Put application.properties file in a different folder in container and tell EI where the application.properties is located in the container:
+    
+    docker run -p 8070:8080 --expose 8080 --volume /path/to/application.properties:/tmp/application.properties -e spring.config.location=/tmp/application.properties eiffel-intelligence-frontend:0.0.19
 
 
 # Run Docker image with provided docker-compose file
 This docker-compose file includes these components, [docker-compose.yml](https://github.com/Ericsson/eiffel-intelligence-frontend/blob/master/src/main/docker/docker-compose.yml):
+
 - MongoDB
 - RabbitMq
 - ER (Event Repository)
@@ -111,8 +112,11 @@ To run docker-compose commands, the environment variables needs to be set:
 Two variables need to be set before we can start up all services with docker-compose tool.
 Set Docker host IP to the HOST variable. This is done automatically when sourcing [env.bash](https://github.com/Ericsson/eiffel-intelligence-frontend/blob/master/src/main/docker/env.bash).
 But it is also possible to do it manually. If on Linux:
-`export HOST=$(hostname -I | tr " " "\n"| head -1)`
-If on Windows, get Docker Host IP with command: `dockermachine ip`
+    
+    export HOST=$(hostname -I | tr " " "\n"| head -1)
+If on Windows, get Docker Host IP with command:
+    
+    dockermachine ip
 Set that Docker host IP to HOST environment variable.
 
 Currently we need to provide EI back-end instances list outside of docker-compose.yml file.
@@ -127,25 +131,23 @@ It will take some minutes until all components has started. When all components
 http://\<docker host ip\>:8081/
 
 Curl command can be used to make request via EI front-end bridge to EI back-end REST API, example for getting all subscriptions:
-
-
-`curl -X GET http://localhost:8081/subscriptions`
+    
+    curl -X GET http://localhost:8081/subscriptions
 
 It is also possible to access these Rest-Api addresses in web-browser and get result presented in a Json view in web-browser.
 
 Following command can be used to get the logs from the EI front-end container/service:
-
-`docker-compose -f src/main/docker/docker-compose.yml logs ei_frontend`
+    
+    docker-compose -f src/main/docker/docker-compose.yml logs ei_frontend
 
 All service names can be retrieved with following command:
-
-`docker-compose -f src/main/docker/docker-compose.yml config --services`
+    
+    docker-compose -f src/main/docker/docker-compose.yml config --services
 
 It is also possible to retrieve the logs by only using "docker logs <container_id or container_name>" command:
-
-`docker logs <container_id or container_name>`
-`docker logs <container_id or container_name>`
+    
+    docker logs <container_id or container_name>
 
 Container id can be retrieved with docker command:
-
-`docker ps`
+    
+    docker ps
diff --git a/wiki/markdown/running-eiffel-intelligence-frontend.md b/wiki/markdown/running-eiffel-intelligence-frontend.md
@@ -0,0 +1,44 @@
+# Running Eiffel Intelligence front-end
+
+## _Prerequisites_
+
+Eiffel intelligence front-end is a Spring microservice distributed in a war file.
+
+To start the service, download the war file from
+[jitpack.io](https://jitpack.io/#eiffel-community/eiffel-intelligence-frontend) and look for the
+latest version. Now replace the latest version in the link below:
+
+    https://jitpack.io/com/github/eiffel-community/eiffel-intelligence-frontend/<version>/eiffel-intelligence-<version>.war
+
+If you want to test the latest code in GitHub clone the project and compile it
+with:
+
+    mvn clean install
+
+append **_-DskipTests_** if you want to skip the tests since the latest on
+master always has passed the tests. The war file should now be found under
+target folder in your cloned project.
+
+If you run from source code, you can run Eiffel-Intelligence front-end with maven command:
+
+    mvn spring-boot:run
+
+Or you can run the executable war file (located in target folder, if running from source code):
+
+    java -jar eiffel-intelligence-frontend-<version>.war
+
+if you want to run with default configuration.
+
+Own configuration can be provided with
+
+    java -jar eiffel-intelligence-frontend-<version>.war --spring.config.location=file:<path to own application.properties>
+
+remember to keep the name of the properties file if you are a beginner to
+Spring. More advanced Spring user can look [here](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html)
+for more information about using external configuration.
+
+If only few properties need to be overriden then use Java opts, for example
+
+    java -jar eiffel-intelligence-frontend-<version>.war -Dspring.data.mongodb.port=27019
+
+All available Eiffel-Intelligence front-end properties can be found in [application.properties](https://github.com/Ericsson/eiffel-intelligence-frontend/blob/master/src/main/resources/application.properties) example file.
diff --git a/wiki/site.xml b/wiki/site.xml
@@ -39,7 +39,10 @@
 
         <menu name="Overview">
             <item name="Home" href="index.html" />
-            <item name="Run in Docker" href="docker.html" />
+            <item collapse="true" name="Running Eiffel Intelligence front-end" href="running-eiffel-intelligence-frontend.html">
+                <item name="Configuration" href="configuration.html" />
+                <item name="Run in Docker" href="docker.html" />
+            </item>
             <item name="GUI overview" href="GUI-overview.html" />
             <item collapse="true" name="Subscription handling" href="subscription-handling.html">
                 <item name="Add Subscription" href="add-subscription.html" />
