Use a local Docker Container

🎯context

You have a Domain Service Java project and want to do local debugging.

Description

This How-To will show you, how you can set up a local Docker container and how to use it for local development for your Java Domain Service project. The container will be running a local instance of Keycloak, MongoDB, Kafka and Apicurio.

Preconditions

You have Docker installed
You have a Java Domain Service project

Steps

Set up the Docker container

Open up a console window

Clone the Java local development tool to your local filesystem and cd into it:

git clone https://github.com/johbossle/java-local-development-tool.git && cd java-local-development-tool

Ensure that the Docker service is running.
Build the container image:
```
docker build -t java-ld-tool:latest .
```
⚠Attention
Please ensure to use LF as line-ending on Windows machines.

Now you can either start an ephemeral container or a named container:

An ephemeral container will be deleted, when you stop it.

docker run -p 2181:2181 -p 9092:9092 -p 27017:27017 -p 9090:8080 -p 8081:8081 --rm java-ld-tool:latest

A named container will not be deleted automatically.

docker run -p 2181:2181 -p 9092:9092 -p 27017:27017 -p 9090:8080 -p 8081:8081 --name java-ld-tool java-ld-tool:latest

❗️The services of this container

MongoDB at mongodb://localhost:27017 without username and password
Keycloak OIDC provider
- username admin and password admin
- admin console at http://localhost:9090
- realm local with a client called local-debugging-app; issuer: http://localhost:9090/realms/local
Kafka with one broker at localhost:9092
Apicurio Registry at http://localhost:8081 without username and password

Set up MongoDB

Connect to your MongoDB Instance at mongodb://localhost:27017 either with the MongoDB Shell or MongoDB Compass.
Create a new database with a name of your choice.
Create a new database collection for every collection that is present in the Solution Designer.

❗️info

You can find the database collections in the 'Infrastructure' tab in the domain namespaces.

Set up Kafka

Create all topics that are used by your application in your local Kafka.
If you want to create the topic dev.event.topic.name with the Kafka CLI Tools use the following commands:

Find out the container ID of the running container:

docker ps

Launch an interactive shell inside your container:

docker exec -it <container-ID or container name> /bin/bash

Create the topic in Kafka:

/opt/kafka_2.13-3.6.0/bin/kafka-topics.sh --bootstrap-server localhost:9092 --topic dev.event.topic.name --create

Set up Apicurio Registry

Open your browser at http://localhost:8081
Upload the event schemas from the folder src/main/resources/schemas/

⚠Attention

The files must be uploaded individually.
If there are multiple schema versions present, you will have to upload all versions in the right order.

Apicurio stores the schemas with whole version numbers, therefore the version in src/main/resources/schemas/schema.json must be changed to the corresponding number. For example from 1.0 to 1.

Set up your project

Copy the file src/main/resources/application-local.template.yaml to src/main/resources/application-local.yaml
Set up the connection to MongoDB. Specify the uri to MongoDB and replace <db-name> with the name of your previously created database.
src/main/resources/application-local.yaml
```
spring.data.mongodb:
    uri: "mongodb://localhost:27017/?"
    database: <db-name>
```

Set up the OIDC provider (Keycloak):

src/main/resources/application-local.yaml
spring.security.oauth2.client:
    provider:
        default:
            issuer-uri: "http://localhost:9090/realms/local"
    registration:
        default:
            client-id: "local-debugging-app"

Enable Swagger UI and set up authentication.

src/main/resources/application-local.yaml
springdoc:
    api-docs:
        enabled: true
        path: /api-docs
    swagger-ui:
        path: /swagger-ui
        oauth:
            clientId: "local-debugging-app"

Enable the Kafka Events Feature.
src/main/resources/application-local.yaml
```
feature:
    kafka-events:
        enabled: true
```

Set up your event topic bindings. You have to specify a topicName for every event you modeled in the Solution Designer.
You need to replace event-topic-binding with the event topic binding name from the Solution Designer.

src/main/resources/application-local.yaml
k5.sdk.springboot.binding.topic:
    topicBindings:
        my-event-topic-binding:
            topicName: "dev.event.topic.name"
            kafkaBinding: "local"
        my-other-topic-binding:
            topicName: "dev.othertopic.name"
            kafkaBinding: "local"
    kafkaBindings:
        local:
            kafka_brokers_sasl: "localhost:9092"
            securityProtocol: "PLAINTEXT"
            password: ""
            user: ""

❗️info

If you are using Event 2.0, you need to make sure that you have set the schema registry configurations correctly.

src/main/resources/application-local.yaml
 k5.sdk.schema-registry:
   schemaRegistryConfig:
     schemaRegistryUrl: "http://localhost:8081"
     schemaRegistrySecurityEnabled: "false"

Run your application

To run your application with the profile created in the previous step, use the following line as a jvm argument when executing your application:

-Dspring.profiles.active=local

Run your application in IntelliJ

Follow these steps to add a run configuration in IntelliJ IDE:

Create a new run configuration
Select 'Application'
Specify your main class
Add the parameter -Dspring.profiles.active=local to the 'VM options'
You can now run your application

Run your application from a terminal

If you want to run your application from a terminal with mvn spring-boot:run, use the following command:

mvn spring-boot:run -Dspring-boot.run.profiles=local

🌟Congratulations!

Your Java project is now running locally.

Description​

Preconditions​

Steps​

Set up the Docker container​

Set up MongoDB​

Set up Kafka​

Set up Apicurio Registry​

Set up your project​

Run your application​

Run your application in IntelliJ​

Run your application from a terminal​