Add graph insight start + configuration WIP

Signed-off-by: Thomas Telleis <[email protected]>

Author: sobo

docs/deploy-and-configure/configuration/graphinsights/explore-add-snapshot.png

@@ -6,28 +6,98 @@ tags:
 ---
 # Graph Insights
 
-## OAuth configuration
 
-Graph Insights requires authentication similar to Explore and Build (DataIntegration).
-There is the need for a client to authenticate in a browser and a second client to allow inter-component communication.
+## Resource consideration
 
-For convenience, by default we use the same clients as for the rest of the application:
+Please refer to [Graph Insights Sizing](../../../deploy-and-configure/requirements/graph-insights-sizing.md) for more information.
 
--   Client for browser: cmem
--   Client for component communication: cmem-service-account
 
-In case you want to have separate clients for production deployments, have a look at the end of this file.
+## Enable Graph Insights
 
-## Resource consideration
+### (a) Enable in docker-compose deployment
+
+In our Corporate Memory docker-orchestration all main configurations can be directed by setting environment
+variables in `environments/config.env`.
+You can find the environments are set as usual in `environments/default.env` and `environments/config.env`.
+
+Add your license to ```licenses/graphinsights.lic``` then start the extension on a already running Corporate Memory
+deployment.
+
+``` console
+mkdir licenses
+ln -s your-license-file.lic graphinsights.
+make enable-extension EXTENSION=graphinsights
+```
+
+Please also have a look at `extensions/README.graphinsights.md`.
+
+### (b) Enable in helm deployment
+
+In helm based deployment you can enable Graph Insights by enable it in your value file.
+It creates a new StatefulSet.
+Preemptive you have to create a secret containing your license file.
+
+``` console
+- "kubectl -n cmem create secret generic graphinsights-license --from-file your-graphinsights.lic
+```
+
+This enables the plugin.
+
+``` yaml
+graphinsights:
+  enabled: true
+```
+
+All needed configuration can be done in the Corporate Memory helm chart `value.yaml` file.
+The configuration mentioned below is rendered with those files, but you usually don't have to touch those:
+
+- `configuration-files/explore-application.yml` for Explore
+- `configuration-files/cmem.integration.config.yml` for Graph Insights
+
+For more details please have a look in the helm value file.
+Every configuration is documented there.
+Please refer to [Kubernetes deployments](../../../deploy-and-configure/installation/scenario-k8s-deployment/index.md) for more information.
 
-Please refer to [Graph Insights Sizing](../../../deploy-and-configure/requirements/graph-insights-sizing.md) for more information.
 
+### Activate and verify the installation
+
+Fist you have enable the Graph Insight in your Explore workspace. By default ist is disabled.
+
+![Explore workspace configuration](explore-workspace-enable-graphinsights.png)
+
+Then you are able to create a snapshot, send it to Graph Insights and select the Graph Insights tab in explore.
+
+![Explore add snapshot](explore-add-snapshot.png)
+
+![Explore select_graphinsights](explore-select-graphinsights-tab.png)
+
+
+
+## Configuration
+
+This section explains the basic configuration of Graph Insights. Since Graph Insights is an application integrated
+into explore, we need to have to configure Explore for the integration and Graph Insights as application itself.
+
+The following chapters explain the configuration in case you want to change the default behavior.
+
+While the extension in the docker-orchestration it is enabled through Spring profiles, we just use the benefits of
+templating in helm and only use one profile.
+
+This is why the configuration differs in both deployments, but we tried to use the same variable names and configuration
+snippets.
 
 ### Explore configuration
 
-The following two sections are needed for enabling Graph Insights inside Explores configuration.
-In the docker orchestration it is enabled through profiles while in helm we just use one profile.
-We there use helm templating mechanism to render it into the default profile.
+In our **docker-orchestration** you find the file which is loaded as `graphinsight` profile
+at `conf/explore/application-graphinsights.yml`.
+Environment variables as usual can be found in `environments/default.env` and `environments/config.env`.
+Sizing can be changed in the loaded memory profile, e.g. at `environments/config.mem.16g.env`.
+The deployment definition for explore with the extension is defined `extensions/docker-compose.graphinsights.yml`
+in the explore service.
+
+In **helm deployments** you find the needed section inside the `.Values.graphinsights.enabled` in file
+at `configuration-files/explore-application.yml`, where most of the configuration is inserted with GO-templates.
+Some environment variables are set in the `value.yaml` and rendered in a ConfigMap `templates/explore-configmap.yaml`.
 
 ``` yaml
 spring.security.oauth2.client.registration.explore-service:
@@ -53,66 +123,123 @@ semspect:
       semspect-dataplatform-url: http://explore/dataplatform
 ```
 
+### Graph Insights configuration
 
-#### (a) helm configuration
+Graph Insights, like Explore, is a Spring Boot application, so it gets configured with environment variables and a YAML
+file.
 
-In helm based deployment you can enable Graph Insights by enable it in your value file.
-Preemptive you have to create a secret containing your license file.
+In our **docker-orchestration** you find the file at `conf/graphinsights/cmem.integration.config.yml`.
+Environment variables as usual can be found in `environments/default.env` and `environments/config.env`.
+Sizing can be changed in the loaded memory profile, e.g. at `environments/config.mem.16g.env`.
+The deployment definition of the extension is defined `extensions/docker-compose.graphinsights.yml`.
 
-``` console
-- "kubectl -n cmem create secret generic graphinsights-license --from-file your-graphinsights.lic
-```
 
-This enables the plugin.
+In **helm deployments** you find the file at `configuration-files/cmem.integration.config.yml`, which is rendered as
+ConfigMap and then mounted into the Graph Insight StatefulSet.
+Environment variables are set in the `value.yaml` and rendered in a ConfigMap `templates/graphinsights-configmap.yaml`.
+Sizing regarding memory, CPU or disk usage are configured in the `value.yaml`.
 
 ``` yaml
-graphinsights:
-  enabled: true
-```
-
-All needed configuration can be done in the Corporate Memory helm chart `value.yaml` file.
-The configuration mentioned above is rendered with those files, but you usally don't have to touch those:
+---
+# for descriptions of the properties s. the same file in https://gitlab.eccenca.com/devops/eccenca-graphinsights-docker
+semspect:
+  extensions: cmem
+  extension.cmem:
+    baseUri: "${DEPLOY_BASE_URL}"
+    authorization:
+      cacheDuration: 60
+  core:
+    enableCaptionPropertySelection: false
+    enableDescriptionPropertySelection: false
+
+frontend:
+  appNameOverride: "Graph Insights"
+  enableLogo: false
+  enableAboutWindow: false
+  singleDatabaseMode: true
+  enableIframeOnlyMode: true
+  enableCopyDeepLink: false
+  fontFamily: "Roboto, helvetica, arial, sans-serif"
+  fontFace: >
+    @font-face {
+          font-family: 'Roboto';
+          font-style: normal;
+          font-weight: 400;
+          src: url('https://eccenca.com/layouts/default/fonts/roboto-v20-latin-regular.woff2') format('woff2');
+    }
+
+  trustedOrigins:
+    - "${DEPLOY_BASE_URL}"
+    - "${DEPLOY_BASE_URL}/*"
+
+  backlink:
+    objectURLTemplate: ${DEPLOY_BASE_URL}/{workspaceID}/explore?resource={objectID}&graph={contextGraphIRI}
+    categoryURLTemplate: ${DEPLOY_BASE_URL}/{workspaceID}/explore?type={categoryID}&graph={contextGraphIRI}
+    objectBacklinkDestination: "CMEM"
+    categoryBacklinkDestination: "CMEM"
+    multiObjectBacklinkDestination: "CMEM"
+  debug: true
+  logLevel: DEBUG
+
+# secure /api/** via resourceserver
+spring.security.oauth2:
+  resourceserver:
+    jwt:
+      jwk-set-uri: "${OAUTH_JWK_SET_URL}"
+  # semspect backend for frontent as oauth2client
+  # To enable SLO add this as back-channel logout uri to the client semspect uses:
+  # http://docker.localhost/graphinsights/logout/connect/back-channel/keycloak
+  client:
+    registration:
+      keycloak:
+        client-id: "${GRAPHINSIGHTS_OAUTH_CLIENT_ID}"
+        authorization-grant-type: "authorization_code"
+        client-authentication-method: "client_secret_basic"
+        # not needed here because we never login to semspect directly
+        redirectUri: "${DEPLOY_BASE_URL}/graphinsights/login/oauth2/code/{registrationId}"
+        # openid is mandatory as spring somehow does not add it to the userinfo request
+        scope:
+          - openid
+          - profile
+          - email
+      # service account used for datastore access
+      semspect-service:
+        client-id: "${GRAPHINSIGHTS_OAUTH_SERVICE_CLIENT_ID}"
+        client-secret: "${GRAPHINSIGHTS_OAUTH_SERVICE_CLIENT_SECRET}"
+        authorization-grant-type: client_credentials
+        provider: keycloak
+    provider:
+      keycloak:
+        issuer-uri: "${OAUTH_ISSUER_URL}"
+        user-name-attribute: "preferred_username"
+
+# same (fixed) session timeout as explore backend
+server.servlet.session.timeout: "36000s"
+server.frame.ancestors: "${DEPLOY_BASE_URL}"
+
+logging:
+  level:
+    root: DEBUG
+    org.springframework: WARN
+    org.springframework.security: WARN
+
+  pattern:
+    console: "%d{yyyy-MM-dd'T'HH:mm:ss.SSSX,UTC} %-5level %logger{15} - %message%n%xException"
 
-- `configuration-files/explore-application.yml` for Explore
-- `configuration-files/cmem.integration.config.yml` for Graph Insights
+```
 
-For more details please have a look in the helm value file.
-Every configuration is documented there.
-Please refer to [Kubernetes deployments](../../../deploy-and-configure/installation/scenario-k8s-deployment/index.md) for more information.
 
-#### (b) docker-compose configuration
+## OAuth configuration
 
-In our Corporate Memory docker-orchestration all main configurations can be directed by setting environments
-variables in `environments/config.env`.
-You can find the environments are set as usual in `environments/default.env` and `environments/config.env`.
+Graph Insights requires authentication similar to Explore and Build (DataIntegration).
+There is the need for a client to authenticate in a browser and a second client to allow inter-component communication.
 
-``` Makefile
-###########################
-# GRAPH-INSIGHTS SETTINGS #
-###########################
-GRAPHINSIGHTS_JAVA_TOOL_OPTIONS="-XX:UseSVE=0"
-
-# This is the client the user uses to login to Graph Insights in browser
-# for convenience we use the same as CMEM client
-# GRAPHINSIGHTS_OAUTH_CLIENT_ID=graph-insights
-GRAPHINSIGHTS_OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID}
-
-# This is the client ID for the Graph Insights service account but not used
-# due to convienience we use the same as CMEM service account
-GRAPHINSIGHTS_OAUTH_SERVICE_CLIENT_ID=graph-insights-service-account
-GRAPHINSIGHTS_OAUTH_SERVICE_CLIENT_SECRET=changeme
-
-GRAPHINSIGHTS_SERVER_PORT=8080
-GRAPHINSIGHTS_SERVER_SERVLET_CONTEXT_PATH=/graphinsights
-# in case of subdomain this have to be adjusted.
-GRAPHINSIGHTS_SERVER_FRAME_ANCESTORS=${DEPLOY_BASE_URL}
-GRAPHINSIGHTS_LOGGING_LEVEL_ROOT=DEBUG
-```
+For convenience, by default we use the same clients as for the rest of the application:
 
-These are used in the configuration files in `conf/explore/application-graphinsights.yml` for Explore settings and
-`conf/graphinsights/cmem.integration.config.yml` for Graph Insights settings.
+-   Client for browser: cmem
+-   Client for component communication: cmem-service-account
 
-The deployment definition can be found here `extensions/docker-compose.graphinsights.yml`
+In case you want to have separate clients for production deployments, have a look at the end of this file.
 
 
 ## Using separate OAuth clients for Graph Insights