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.

Warning:

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

Adjust the following configuration for toggling deployment features: (only affecting project during local runtime, not to be confused with Extensions)

# To enable / disable some auto configuration features
feature:
  # toggle security for rest apis - if turned off, api calls are no longer secured
  security:
    enabled: true
  # toggle openapi - if turned off, openapi specification is no longer used
  openapi:
    enabled: true
  # toggle narayana security - if turned off, saga transactions are no longer secured
  secure-narayana:
    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 use a Swagger UI for local development, the Swagger UI Support extension needs to be enabled. You can enable the extension for your project via the extensions page in the Solution Designer.

After starting the application locally, the Swagger UI can be accessed from the following URL: localhost:8080/{service-acronym}/swagger-ui/index.html

Tip:

The Swagger UI URL is dependent on the configured path in your application.yaml or application-local.yaml. We recommend to set the value of springdoc.swagger-ui.path to /${solution.acronym}/swagger-ui to make use of the above described URL. If no specific value is set, the Swagger UI will be available under localhost:8080/swagger-ui/index.html

For proper usage of a clientId in the Swagger UI, please ensure that you use the following settings in your application-local.yaml:

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>

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.