Skip to content

smartSenseSolutions/spring-boot-multi-module-boiler-plate

Repository files navigation

Seed Multi module demo

Spring boot multi module boiler plate

This repository contains boiler-plate codebase using Java, Spring boot as core technology.

Developer Documentation

To run application locally, this section describes the tooling as well as the local development setup.

Module Information

ss-api : It contains utilities like constants, dtos, validators, utility classes. This will be published as a package and this can be used by other Java projects as a depedency

ss-dao : It contains database entities and repositories.

ss-service : It contains abstraction of business logic.

ss-service-impl : It contains business login.

ss-web : This is runnable spring boot application. It contains application Configs, Db-migration files, Exception handler, API definition.

Tooling

Area Tool Download Link Comment
IDE IntelliJ https://www.jetbrains.com/idea/download/ Additionally the envfile plugin is suggested
Build Gradle https://gradle.org/install/
Runtime Docker https://www.docker.com/products/docker-desktop/
Database DBeaver https://dbeaver.io/
IAM Keycloak https://www.keycloak.org/

Local Development Setup

  1. Run MainApplication.java in IDE. It will up database and keycloak using docker compose(ref: Spring boot support for docker compose)
  2. Open API doc on http://localhost:8080/api/app/ui/swagger-ui/index.html
  3. Click on Authorize on swagger UI and on the dialog click again on Authorize.
  4. Login with username=valid-user and password=password

Build application locally

Build with test cases

./gradlew build

Build without test cases

./gradlew build -i -x test

Test Coverage

Jacoco is used to generate the coverage report. The report generation and the coverage verification are automatically executed after tests.

The generated HTML report can be found under jacoco-report/html/

To generate the report run the command

./gradlew testCodeCoverageReport

To check the coverage run the command

./gradlew jacocoTestCoverageVerification

Common issues and solutions during local setup

1. Can not build with test cases

Test cases are written using the Spring Boot integration test frameworks. These test frameworks start the Spring Boot test context, which allows us to perform integration testing. In our tests, we utilize the Testcontainers library (https://java.testcontainers.org/) for managing Docker containers. Specifically, we use Testcontainers to start PostgreSQL and Keycloak Docker containers locally.

Before running the tests, please ensure that you have Docker runtime installed and that you have the necessary permissions to run containers.

Alternative, you can skip test during the build with ./gradlew clean build -x test

2. Database migration related issue

We have implemented database migration using Liquibase (https://www.liquibase.org/). Liquibase allows us to manage database schema changes effectively.

In case you encounter any database-related issues, you can resolve them by following these steps:

  1. Delete all tables from the database.
  2. Restart the application.
  3. Upon restart, the application will recreate the database schema from scratch.

This process ensures that any issues with the database schema are resolved by recreating it in a fresh state.

Environment Variables

name description default value
APP_PORT port number of application 8080
SECURITY_ENABLE To keep spring security enable/disable true
KEYCLOAK_REALM_NAME Realm name of keycloak SWD
KEYCLOAK_CLIENT_ID Keycloak public client id pb_backend
KEYCLOAK_ROLE_CLIENT_ID Keycloak private client id pb_backend
KEYCLOAK_AUTH_URL Keycloak server url http://localhost:9090/auth
DB_HOST Database host localhost
DB_PORT Port of database 5432
DB_NAME Database name multi-module-demo
USE_SSL Whether SSL is enabled in database server false
DB_USER Database username
DB_PASSWORD Database password
MULTIPART_MAX_FILE_SIZE Max multiple file size 50 MB
MULTIPART_MAX_REQUEST_SIZE Max multiple part request size 51 MB
RETRY_CONNECTION_TIMEOUT_MILLI Duration in millis for retry connection timeout 200
RETRY_READ_TIMEOUT_MILLI Duration for read timeout 500
RETRY_MAX_IDLE_CONNECTION Duration for idle connection 10
RETRY_ALIVE_DURATION_MIN Duration for retry alive 5
RETRY_MAX_ATTEMPT Max retry attempt 5
RETRY_INTERVAL_MILLI Duration between retry 2000

Reference of external lib

  1. https://www.testcontainers.org/modules/databases/postgres/
  2. https://github.com/dasniko/testcontainers-keycloak
  3. https://github.com/smartSenseSolutions/smartsense-java-commons