Backend Java Spring Boot Quickstarter

Purpose of this quickstarter

Use this quickstarter to generate a spring boot based project.

It will provide a java 21 project with preconfigured gradle build and CI/CD integration (Jenkinsfile).

What files / architecture is generated?

The quickstarter uses the spring boot project generator service hosted by Spring (https://start.spring.io) to generate the spring boot project.

This is implemented in the quickstarter jenkins build script called Jenkinsfile (open it to understand the internal of the code generation of this quickstarter).

When provisioning this quickstarter in the provisioning app a spring boot project based on version 3.2.0 will be generated and pushed to your git repository.

The generated project requires java 21 and includes the required gradle build and wrapper artifact based on gradle version 8.5.

Project Structure

The generated spring boot project contains following folders:

  • src (java project structure)

  • gradle (gradle wrapper portable distribution)

  • docker (include the Dockerfile used to build the image to be deployed during CI/CD to openshift)

Gradle Support

The generated project includes a gradlew wrapper which is a portable distribution of gradle. It allows you to easily build the project without any further tool installation other than java.

Gradle Artifacts

You´ll find in the project following gradle artifacts:

  • build.gradle (build definition)

  • gradlew.bat

  • gradlew

  • gradle/wrapper/gradle-wrapper.jar

  • gradle/wrapper/gradle.properties

  • settings.gradlew

gradle.properties is missing. This is on purpose, because you need to define it on your own by providing your nexus configuration.

Nexus configuration in gradle.properties

You´ll need to create gradle.properties yourself and add following properties:

nexus_url=<URL_OF_YOUR_NEXUS_SERVER>
nexus_user=<YOUR_NEXUS_USERNAME>
nexus_pw=<YOUR_NEXUS_PASSWORD>

Optionaly you can add

nexus_folder_releases=<FOLDER_TO_UPLOAD_RELEASE_ARTEFACTS> (ie. maven-releases)
nexus_folder_snapshot=<FOLDER_TO_UPLOAD_SNAPSHOT_ARTEFACTS> (ie. maven-snapshots)

If you do not want to use Nexus at all, just define the following property:

no_nexus=true

Run gradlew -v to verify the installed version of gradle wrapper.

Uploading artifacts via gradle

The build is prepared to upload generated artifacts to a nexus repository via the gradle maven-puplish plugin. If the artifact has a SNAPSHOT-Version, the nexus folder maven-snapshots is used, otherwise it uses the folder maven-releases. This folders are used per default.

You can override this default configuraiton by specifing the properties nexus_folder_releases and nexus_folder_releases in gradle.properties. Overriding this configuration can also be achieved by setting the environment variables NEXUS_FOLDER_RELEASES and NEXUS_FOLDER_SNAPSHOTS.

Upload to nexus is prepared in Jenkinsfile, but disabled per default. See section How this quickstarter is built thru jenkins below for details.

Dependencies and Frameworks used

The generated spring boot project is preconfigured with some third party dependencies (i.e. --dependencies="web,data-rest,data-jpa,h2,security,devtools"), which are defined in the quickstarter jenkins build script called Jenkinsfile (open it to understand the internal of the code generation of this quickstarter).

Look in method dependencies in the file build.gradle to review the defined dependencies.

ODS Integration (Jenkinsfile)

The project includes a special artifact that enables it to integrate with OpenDevStack CI/CD infrastructure. The Jenkinsfile provides this capability. Basically it is the script that is executed in Jenkins every time a push to your git repository is done. More on this below.

Usage - how do you start after you provisioned this quickstarter

After the provisioning the provisioning app will display the url of git repository. This git repository contains the generated project artifacts as describe above in Project Structure.

To start working with it you´ll need to clone the git repository in your local development environment. After cloning it use ./gradlew build to verify that the project compiles and test runs.

java 21 or later version is required to run gradlew and compile java classes.

Metadata

The following are typical metadata values that can be used for components based on this quickstarter: Note that the OpenShift resources will be labeled based on this metadata.

name: <the component id (this is the default, if omitted)>
description: "Some microservice implemented in Java over Spring Boot"
supplier: https://example.com
version: 1.0.1
type: ods
role: backend
runtime: spring-boot
runtimeVersion: 3.2.0

How this quickstarter is built thru jenkins

The Jenkinsfile implements the CI/CD pipeline of your project.

The Jenkinsfile is kind of configuration that customizes the core pipeline implemented by jenkins shared library. It is highly recommended that you familiarize with this file and library.

It is executed in Jenkins every time a push to your git repository is done. Basically, the tasks implemented by this pipeline are:

  1. clone the branch in the Jenkins environment

  2. run the java build by calling method stageBuild

  3. execute sonarqube analysis (via calling shared library method stageScanForSonarqube)

  4. Optionally: deploy to nexus (via calling method stageUploadToNexus). Note that this is disabled per default. To enable, please remove the comment on line stageUploadToNexus in Jenkinsfile

  5. build a docker image (via shared library method stageStartOpenshiftBuild)

  6. deploy the docker image to openshift (via shared library method stageDeployToOpenshift)

The 2nd step executes gradlew build to compile your project and create a distribution as jar file. This file is copied to the docker folder to be included in the docker image when the image is built in step 5.

include::partial$secret-scanning-with-gitleaks.adoc

Builder agent used

This quickstarter uses the jdk Jenkins builder agent.

Migration to Java 21

The jdk builder agent Jenkins builder agent has installed 3 JDK: java 11, java 17 and java 21. The default version is java 11. This makes the agent backwards compatible.

If you are migrating an ODS-based spring boot project to java 21 following instructions provide a some guidance about the typical steps to achieve this:

  • change the agent version as indicated in jdk builder agent

  • upgrade the gradle wrapper to version 8.5 running this gradle command at the root folder of your spring project:

gradle wrapper --gradle-version 8.5 --distribution-type bin
this command use just gradle instead of the wrapper.

  • commit and push the changes to the remote git project repository. Following files are expected to be included in the change:

./gradlew (or gradlew.bat depending on your environment)
./gradle/wrapper/gradle-wrapper.jar
./gradle/wrapper/gradle-wrapper.properties

  • verify that the jenkins build pipeline run successful. Fix any error if is not the case.

  • change your local runtime to java 21 and compile your project with the gradle wrapper.

  • update in your build.gradle file the source compatibility to sourceCompatibility = JavaVersion.VERSION_21 and compile again.

  • update the project Jenkinfile by adding in the stage Build and Unit Test a call to the use-j21.sh before the gradle wrapper. This will set the runtime to `java 21. It would look like this:

def status = sh(script: "use-j21.sh && ./gradlew clean build --stacktrace --no-daemon", returnStatus: true)

  • commit and push the changes to the remote git project repository.

  • verify that the jenkins build pipeline run successful. Fix any error if is not the case.

Known limitations

NA