Setup Java local profile

Prerequisites

At this point it is assumed, that the initial setup and the mandatory commands of the Solution CLI have been performed and executed as described here.

Now its always helpful if you can run, test and debug your service project locally. To achieve that we need to provide some needed configuration.

Configuration approaches

Have a valid deployed project and use its k8s configuration maps to load bindings for your database and Kafka.
Provide configuration values to connect to your local database and Kafka broker.

Attention: If you choose to use deployed project k8s configuration maps, you need to log in to your OpenShift cluster via oc CLI and run proper oc proxy command to be able to connect to your OpenShift namespace Database and Kafka clusters.

Setting up local profile

Tip: Use `/src/main/resources/application-local.template.yaml` as the basis to create an `application-local.yaml` file and override properties needed for the local profile.

First add your service project acronym:

solution:
    acronym : "project acronym"

Dependent on the features relevant for your project, please see below sections for further configurations (database, kafka, Swagger UI settings).

OpenShift k5-project namespace bindings

Note: How to use bindings from the OpenShift k5-project is depending on whether your project is based on Java Spring Boot Stack 1.0 or Java Spring Boot Stack 2.0

Java Spring Boot Stack 2.0

To load bindings from the OpenShift k5-project namespace use the following configuration:

k5.sdk.springboot.kubernetes.namespace: <k5-Project>

Java Spring Boot Stack 1.0 (Deprecated)

To load bindings from the OpenShift k5-project namespace use the following configuration:

de:
  knowis:
    cp:
      consumer:
        kubernetes:
          namespace: <k5-Project>

Auto configuration features

To enable / disable some auto configuration features, please adjust the following configuration:

  feature:
    kafka-events:
      enabled: true
    mongo:
      enabled: true
    security:
      enabled: true
    openapi:
      enabled: true
    webmvc:
      enabled: true

Database configuration

Depending on your service project selected Persistence Type or , you can configure your database as below.

MongoDB persistence

Load MongoDB configuration from k8s configuration map

spring:
  data:
    mongodb:
        secretName: # read from kubernetes secret

To access a local MongoDB, you can set the spring.data.mongodb.uri property to change the URL and configure additional settings, as shown in the following example:

spring:
  data:
    mongodb:
      uri: mongodb://<username>:<secret>@<host>:<port>/<database>
      database: <database>

Alternatively, you can specify connection details using discrete properties. For example, you might declare the following settings as shown below:

spring:
  data:
    mongodb:
      host: <host>
      port: <port>
      database: <database>
      username: <username>
      password: <password>

RDBMS Persistence

To access your service project RDBMS database, you need to add below configuration

spring:
  datasource:
    url: "jdbc:<subprotocol name>://<host>:<port>/<database-name>"
    username: <user name>
    password: <password>
    driver-class-name: <Your database driver class>

Kafka configurations

Load event topic binding configuration from k8s secret(s)

You need to add your k5-project as described in Here
You need to have proper oc proxy and oc port forwarding to be able to access your OpenShift k5 project event topic binding secret(s) and their configured Kafka cluster.

Alternatively, you can configure to use your Kafka broker and your own local topic binding secret(s).

Install and configure your Kafka broker see https://kafka.apache.org/quickstart
For each topic add proper event topic binding configuration like below

Java Spring Boot Stack 2.0

k5.sdk.springboot.binding.topic:
  topicBindings:
    <Topic-Alias-1>: 
      topicName: "<Kafka topic name>"
      kafkaBinding: "<Kafka-Secret-1>"
    <Topic-Alias-2>: 
      topicName: "<Kafka topic name>"
      kafkaBinding: "<Kafka-Secret-2>"
  kafkaBindings:
    <Kafka-Secret-1>:
      kafka_brokers_sasl: ""
      password: ""
      user: ""
    <Kafka-Secret-2>:
      kafka_brokers_sasl: ""
      password: ""
      user: ""

Java Spring Boot Stack 1.0 (Deprecated)

de.knowis.cp.binding.topic:
  topicBindings:
    <Topic-Alias-1>: 
      topicName: "<Kafka topic name>"
      kafkaBinding: "<Kafka-Secret-1>"
    <Topic-Alias-2>: 
      topicName: "<Kafka topic name>"
      kafkaBinding: "<Kafka-Secret-2>"
  kafkaBindings:
    <Kafka-Secret-1>:
      kafka_brokers_sasl: ""
      password: ""
      user: ""
    <Kafka-Secret-2>:
      kafka_brokers_sasl: ""
      password: ""
      user: ""

Note: Kafka broker user and password are optional if your Kafka broker is not secured.

Swagger UI

To configure Swagger UI for local development, use the settings below:

springdoc:
  swagger-ui:
    oauth:
      clientId: <client-id>

If you have spring-security-oauth2-client on your classpath, you can take advantage of some auto configuration to set up an OAuth2/Open ID Connect client, as shown in the following example:

spring:
  security:
    oauth2:
      client: #Spring Security OAuth2  config
        provider:
          default:
            issuer-uri: <issuer-uri>
          <client-id>: 
            jwk-set-uri: <jwk-set-uri>
            token-uri: <token-uri>
            issuer-uri: <issuer-uri>
        registration: 
          default:
            client-id: <client-id>
          <client-id>: # only required if the access type of the client is not public
            client-id: <client-id>
            client-secret: <secret>

Schema registry configurations

Note: How to configure a schema registry for local development, is depending on whether your project is based on Java Spring Boot Stack 1.0 or Java Spring Boot Stack 2.0

Java Spring Boot Stack 2.0

To configure a schema registry for local development, please use the following settings:

k5.sdk.springboot.schema-registry:
  schemaRegistryConfig:
    schemaRegistryUrl: <schema-registry-url>
    schemaAuthServerUrl: <schema-auth-server-url>
    authRealm: <auth-realm>
    clientSecret: <client-secret-token>
    clientId: <client-id>

Java Spring Boot Stack 1.0 (Deprecated)

To configure a schema registry for local development, please use the following settings:

de.knowis.schema-registry:
  schemaRegistryConfig:
    schemaRegistryUrl: <schema-registry-url>
    schemaAuthServerUrl: <schema-auth-server-url>
    authRealm: <auth-realm>
    clientSecret: <client-secret-token>
    clientId: <client-id>

Saga configurations

Note: The Saga pattern is only available for Domain Services (Java) based on Java Spring Boot Stack 2.0

If you want to use the Saga pattern in your project for implementing transactional use cases, the application-local.yaml needs to have additional configurations. The Saga extension is implemented by Apache Camel which requires the below defined settings:

camel:
  lra:
    coordinator-url: <camel-server-url>
    local-participant-url: ${k5.sdk.springboot.server.baseurl}/camel
    local-participant-context-path: ""

Note: Please consider, that the LRA coordinator might not be able to trigger the callbacks if your service is running locally

Configure OAuth settings

In order to communicate with the lra-coordinator when security is enabled, it is required to configure an additional client to be able to call the lra-coordinator.

To configure the additional client, please use the following settings (e.g. you can get the values from secret dashboard-oauth-client-secret):

spring:
  security:
    oauth2:
      client: 
        provider:
          <the_client_registration_id>:
            token-uri: "<the_token_uri>"
            jwk-set-uri: "<the_jwk_set_uri>"
        registration:
          <the_client_registration_id>:
            client-id: "<the_client_id>"
            client-secret: "<the_client_secret>"
            authorizationGrantType: "client_credentials"

k5:
  sdk:
    springboot:
      oidc:
        clientRegistrationId: "<the_client_registration_id>"

Running with local profile

Create a new Run Configuration for a Java Application. Pass the configuration below as jvm arguments to use the local profile.

-Dspring.profiles.active=local

Further configurations

Note: This is only relevant for projects based on Java Spring Boot Stack 2.0

According to the following issue https://github.com/spring-projects/spring-data-mongodb/issues/4237, using date or dateTime properties in entities or root entities can cause problems. To mitigate this problem, please adjust your run configuration and add --add-opens=java.base/java.time=ALL-UNNAMED so that it looks like the following:

-Dspring.profiles.active=local --add-opens=java.base/java.time=ALL-UNNAMED

Build and run the code.

Note: Refer to Spring Boot's official documentation for more details on Database and Kafka additional configuration.