Skip to content

Setting up the Environment

This tutorial will enable you to develop Spring Boot OpenCQRS applications by introducing you to the necessary building blocks used throughout this Getting Started series. This involves the required infrastructure components and project dependencies. You will be creating an initial, running Spring Boot application, that will be extended throughout the following tutorials.

Prerequisites

In order to create and run the OpenCQRS Spring Boot App, you need the following tools:

  • JDK 21+

    Install a JDK with minimum version 21 to develop the app.

    Download OpenJDK

  • IDE

    Use your preferred IDE, such as IntelliJ IDEA to write the code.

    Download IntelliJ

  • Docker

    Install Docker to run additional, required backend services.

    Download Docker

  • curl

    Install curl (or any equivalent HTTP client) to test the application.

    Download curl

System Architecture Overview

The following diagram depicts the components used to build and test the application:

block-beta
    columns 3

    space Client["Client\n(curl)"] space
    space space space
    space App["Spring Boot Web App"] space
    ESDB[("Event Store\n(EventSourcingDB)")] space Database[("Database\n(H2)")]

    Client --> App
    App --> ESDB
    App --> Database
  • The Client represents real-world client applications interacting with the REST API provided by our Spring Boot application.
  • The Spring Boot Web App implements the domain and business logic to handle client requests.
  • The EventSourcingDB is responsible for storing and reading the events published and consumed by the application, respectively. It represents the event store, which is the primary storage for our application.
  • The Database is a SQL database storing secondary data, i.e. data projections from existing events, and provides the necessary data for client queries.

Warning

For a simplified setup of the infrastructure components an in-memory (H2) database will be used, which is fully integrated into the life-cycle of the Spring Boot application. This, however, implies that data stored therein will be lost upon restart of the application or has to be recreated from the primary storage (event store), if necessary.

Running the EventSourcingDB

The EventSourcingDB is an infrastructure component that needs to be started independently of the Spring Boot app. You can start it using Docker, as follows:

docker run --rm -it \
    --publish 3000:3000 \
    docker.io/thenativeweb/eventsourcingdb:1.0.3 run \
    --api-token secret \
    --data-directory-temporary \
    --http-enabled=true \
    --https-enabled=false

docker run --rm -it ^
    --publish 3000:3000 ^
    docker.io/thenativeweb/eventsourcingdb:1.0.3 run ^
    --api-token secret ^
    --data-directory-temporary ^
    --http-enabled=true ^
    --https-enabled=false

The database will be listening on TCP port 3000 with the access token secret, which can be verified by querying its /ping endpoint as follows: 

curl --request GET --url "http://localhost:3000/api/v1/ping"
If running correctly, this should yield OK as response.

Creating an initial Spring Boot App

You will need to create a new Spring Boot application with Spring Web, Spring Boot Actuator, H2 Database, and Spring Data JPA support:

  • Spring Web will enable us to implement REST API endpoints
  • Spring Boot Actuator provides us with health monitoring for the application and its infrastructure components
  • H2 Database will serve as secondary SQL data store
  • Spring Data JPA provides simpler data access to the H2 SQL database

Choose from any of the following options to create the application:

Spring Boot version

Spring Boot's version is constantly increasing. You may use any stable Spring Boot version newer than 3.4.6 as well, in the following.

The Spring Initializr is available at start.spring.io. Use it to configure the application settings as shown in the following screen shot. Make sure to select Java 21+ and include the Spring Web, Spring Boot Actuator, H2 Database, and Spring Data JPA dependencies.

Tip

Alternatively, you may use the following bookmark to preselect the required options.

Spring Initializr Settings Click the Generate-Button and download the application ZIP file. Extract it anywhere in your home directory, and open or import it using your preferred IDE.

IntelliJ IDEA Ultimate may be leveraged to create a new Spring Boot app directly from within the IDE. Use File -> New -> Project... and select Spring Boot to configure the application, as shown in the following wizard screenshots: IntelliJ Spring Boot Step 1 IntelliJ Spring Boot Step 1 IntelliJ will generate and open the application for you automatically.

After having set up the new Spring Boot application project, add the OpenCQRS to your project's dependencies. Choose one of the following options to add the highlighted lines to your build script (depending on the build system chosen before):

build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    implementation("org.springframework.boot:spring-boot-starter-web")
    runtimeOnly("com.h2database:h2")
    implementation("com.opencqrs:framework-spring-boot-starter:1.0-rc6")
    testImplementation("com.opencqrs:framework-test:1.0-rc6")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    runtimeOnly 'com.h2database:h2'
    implementation 'com.opencqrs:framework-spring-boot-starter:1.0-rc6'
    testImplementation 'com.opencqrs:framework-test:1.0-rc6'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
pom.xml
<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>com.opencqrs</groupId>
            <artifactId>framework-spring-boot-starter</artifactId>
            <version>1.0-rc6</version>
        </dependency>
        <dependency>
            <groupId>com.opencqrs</groupId>
            <artifactId>framework-test</artifactId>
            <version>1.0-rc6</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

Spring Boot Project Contents After having successfully opened or imported the application project into your favorite IDE, you should see a CqrsExampleApplication class, which represents the main Spring Boot application class, needed to start the application. This may look similar to the screenshot from IntelliJ.

Configuring the Application

The Spring Boot applications requires some additional configuration, so the following lines should be placed within the application.properties:

src/main/resources/application.properties
spring.application.name=library-service
server.port=8080

esdb.server.uri=http://localhost:3000
esdb.server.api-token=secret

management.endpoint.health.show-components=always

The configuration assures, that:

  • the application is named appropriately for later event publishing
  • the HTTP listen port is configured to 8080
  • the connection to the EventSourcingDB is configured
  • Spring Boot Actuator provides more detailed health information (including the ESDB health)

Running the Application

With the EventSourcingDB running, the application can finally be started as follows:

./gradlew bootRun

gradlew.bat bootRun

./mvnw bootRun

mvnw.bat bootRun

To ensure it is running properly and connects to the EventSourcingDB and the H2 database correctly, use the following command:

curl --request GET --url "http://localhost:8080/actuator/health"

This should yield the following output: 

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP"
    },
    "diskSpace": {
      "status": "UP"
    },
    "esdb": {
      "status": "UP"
    },
    "ping": {
      "status": "UP"
    },
    "ssl": {
      "status": "UP"
    }
  }
}

Now you are ready to proceed with the remaining tutorials to learn how to implement OpenCQRS applications.