Dummy Service

TODO - In cloned project, remove badge URLs above (replace instructions in the setup section)

TODO - In cloned project, update description

This is a template project for Spring Boot based microservices. It's goal is to simplify starting a new project with popular features ready out of the box and nothing more. Since this project is simplified, without additional changes it is rather intended for internal (not public API) or hobby projects. Template covers also CI/CD workflows and integration with a quality scan.

But why?

TODO - In cloned project, remove this section

One may ask: Why not to use Spring Initializr or JHipster instead of the template? Well, there are few reasons...

1. I am really picky when it comes to code standards (see above). Initializr and JHipster are both great tools (actually, this project was initially started with Initializr) but after using them I always find myself correcting tons of small imperfections here and there.
2. Initializr does not support Spock which is my favourite tests framework.
3. JHipster generates lots of super-must-have-cloud-code (after all, its hipster stuff ;-)). It is great when you try to spin a startup, but in many cases it is superfluous for small - internal or hobby - projects.
4. Both tools do not cover CI/CD workflows.

Another interesting question: Why not to use one of zillion (actually, around 2-3k) template projects available on the GitHub? Indeed, some of them could be close to my needs but...

1. I started one of my hobby projects as monolith and just later decided to cut it into microservice pieces. So I had a need for a template similar as much as possible to the original project's structure to avoid extra effort.
2. Creating this template was an interesting exercise.
3. Did I mention I am picky? Even good templates do not cover all of my requirements.

Toolchain

• Gradle
• Spring Boot
• Spring Boot Actuator
• Spring Boot Dev Tools
• Spring Boot Admin
• Spring MVC
• Spring Data JPA
• Spring Data Redis
• Java Validation Framework (JSR 380)
• Lombok
• MapStruct
• ShedLock
• Resilience4J
• PostgreSQL
• Redis
• Springdoc-OpenAPI
• OpenAPI Generator
• Liquibase
• Spock Framework
• WireMock
• Testcontainers and Playtika
• GitHub Actions
• SonarCloud
• Docker

For the full list see the build.gradle.

Architecture

Design, code structure and naming convention were inspired by:

• Onion / Clean / Hexagonal Architecture
• Domain Driven Design (DDD)

If one wants to read more about combining all these together, here is an interesting article.

Project Setup From Template

TODO - In cloned project, remove this section

Clone repository

Please note: One should already have GitHub account.

1. Create a new repository from this template.
2. Import/clone project to IDE
3. Modify build.gradle
   1. Change application group and description.
   2. Reload Gradle project.
4. Update README
   1. Update or remove sections marked with TODO flag
   2. Optional - add CI/CD badge to README (GitHub Actions / CICD Workflow / '3 dots button')
   3. Optional - change license.
5. Push changes to GitHub.

Please note: Application root package, and many of the template classes/resources hold dummy label. It is recommended to change these names after a project setup.

SonarCloud integration

Please note: One should already have SonarCloud account authorized as an application in GitHub. Additionally, CI/CD script assumes that one logs to SonarCloud with GitHub account.

1. Add new project analyze in SonarCloud (choose GitHub Actions as an analysis method).
2. Copy SonarCloud token and add to GitHub repository secrets as SONAR_TOKEN.
3. Optional - add SonarCloud badges to README (SonarCloud project home page, lower right corner):
   1. Quality Gate Status
   2. Lines of Code
   3. Coverage
4. In SonarCloud, define new code based on a previous version (Administration / New Code).
5. Push changes to GitHub.

DockerHub integration

Please note: One should already have DockerHub account. Additionally, CI/CD script assumes that both GitHub and DockerHub share the same account id.

1. Create new DockerHub repository.
2. Add DockerHub password to GitHub repository secrets as DOCKERHUB_PASSWORD.
3. Service image will be published to DockerHub on the next release.

Overview

TODO - In cloned project, provide here service design and/or diagrams

Usage

TODO - In cloned project, provide here usage description

Developer Guide

Prerequisites

Project development requires following software being installed on a developer's machine:

Tool	Version	Comment
Git	latest
JDK	15	AdoptOpenJDK is recommended
IDE	latest	IntelliJ IDEA is recommended
Docker Desktop	2.4 or newer

Please note: Project does not depend on IntelliJ IDEA specific features. Feel free to use Eclipse or Notepad instead :)

Optionally, consider installing IDE plugins that improve development experience. Recommended plugins should have versions available for most popular IDEs (IntelliJ links below):

Plugin	Comment
Lombok	Support for Lombok generated code
MapStruct	Support for MapStruct generated code
Docker	Support for docker-compose (handy when starting application locally)
SonarLint	Quality feedback on the fly
PlantUML	Helps writing diagrams with PlantUML

Please note: Without some of these plugins, IDEs may highlight references to generated code (e.g. Lombok properties or MapStruct mappers) as errors. It is annoying but do not affect building or running application.

Environment

Development environment is provided as a code by Docker Compose. It may be controlled with standard docker commands or using Gradle tasks:

• composeUp - starts dev-env as Docker Compose services (waits until services are up and running)
• composeDown - stops dev-env (all the data is wiped, including database content)

For example, following command starts dev-env:

./gradlew composeUp 

Once started, following services are available:

Service	URL	Credentials
pgAdmin	http://localhost:81	admin@localhost / admin
Spring Boot Admin	http://localhost:82	admin / admin
Swagger UI	http://localhost:83/swagger	n/a
PostgreSQL	http://localhost:5432	dev / dev
Redis	http://localhost:6379	n/a

Build

Project build is powered by Gradle wrapper with additional plugins (e.g. java, spring-boot, docker-compose). Few most useful build tasks:

• clean - cleans the build
• test - executes unit and integration tests
• build - builds the application (and executes tests)

For example, following command runs a clean build:

./gradlew clean build 

Run

Service, as a regular Spring Boot application may be started locally by running main application class or using Gradle task:

• bootRun - starts application (compiles and builds code if needed)

Since application to start requires development tools to be up and running, one may combine Gradle tasks to launch complete development environment with a single command, e.g.:

./gradlew composeUp bootRun 

Once started, application listens on http://localhost:8080. Status of the running application can be checked using one of the Actuator endpoints, e.g.:

• http://localhost:8080/actuator/info - general info
• http://localhost:8080/actuator/health - health status

Please note: Project includes spring-boot-devtools "that can make the application development experience a little more pleasant", e.g. provides code changes detection and automatic restarts.

License

This software is released under the MIT Open Source license.