Forem: vlaship

SpringBoot Web Service - Part 5 - Github Action

vlaship — Sun, 05 Jan 2025 20:46:41 +0000

GitHub Actions provide a seamless way to integrate CI/CD into your repository, automating various tasks like running tests, building artifacts, and deploying your project.

Workflow for SNAPSHOT

This workflow is triggered on non-main branches or manually through the workflow dispatch event. It includes the following steps:

Run tests: Ensures that your code passes all tests.
Build the JAR file: Compiles your Spring Boot application.
Build Docker image and push it to GitHub Docker Registry: Creates a Docker image from the generated artifact and pushes it to the GitHub Container Registry.

name: Test and Build Snapshot

on:
  push:
    branches-ignore:
      - main
  workflow_dispatch:

permissions:
  contents: read
  packages: write

jobs:
  maven-verify:
    if: "!contains(github.event.head_commit.message, '[skip ci]')"

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven
          cache-dependency-path: '**/pom.xml'

      - name: Verify
        run: mvn -B clean verify --file pom.xml

  maven-build:
    needs: maven-verify
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven
          cache-dependency-path: '**/pom.xml'

      - name: Build
        run: mvn -B package --file pom.xml

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: app.jar
          path: target/*.jar

  docker-build-push:
    needs: maven-build
    runs-on: ubuntu-latest
    env:
      CURRENT_VERSION: ''

    steps:
      - uses: actions/checkout@v4

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: app.jar
          path: target

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GHCR_PAT }}

      - name: Get Version
        run: echo "CURRENT_VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)" >> $GITHUB_ENV

      - name: Build Docker image
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}:${{ env.CURRENT_VERSION }}-${{ github.run_id }}

Workflow for RELEASE

This workflow runs when changes are pushed to the main branch and includes the following steps:

Build the release version: Compiles the release version of your project.
Build Docker image and push it to GitHub Docker Registry: Creates and pushes the Docker image to the GitHub Container Registry.
Increment SNAPSHOT version: Updates the version in pom.xml for future snapshot versions.

name: Build Release

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  packages: write

jobs:
  maven-build-release:
    if: "!contains(github.event.head_commit.message, '[skip ci]')"

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven
          cache-dependency-path: '**/pom.xml'

      - name: Prepare Release Version
        run: mvn versions:set -DremoveSnapshot

      - name: Build
        run: mvn -B clean package --file pom.xml -DskipTests

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: app.jar
          path: target/*.jar

  docker-build-push:
    needs: maven-build-release
    runs-on: ubuntu-latest
    env:
      CURRENT_VERSION: ''

    steps:
      - uses: actions/checkout@v4

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: app.jar
          path: target

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GHCR_PAT }}

      - name: Get Version
        run: |
          mvn versions:set -DremoveSnapshot
          echo "CURRENT_VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)" >> $GITHUB_ENV

      - name: Build Docker image
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}:${{ env.CURRENT_VERSION }}-${{ github.run_id }}

  increment-version:
    needs: docker-build-push
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GIT_PAT }}

      - name: Configure Git
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"

      - name: Increment Snapshot Version
        run: |
          # Extract current version and increment patch version
          CURRENT_VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
          MAJOR=$(echo $CURRENT_VERSION | cut -d. -f1)
          MINOR=$(echo $CURRENT_VERSION | cut -d. -f2)
          PATCH=$(echo $CURRENT_VERSION | cut -d. -f3 | cut -d- -f1)
          NEW_PATCH=$((PATCH + 1))
          NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH-SNAPSHOT"

          # Update version in pom.xml
          mvn versions:set -DnewVersion=$NEW_VERSION
          mvn versions:commit

          # Commit and push the new snapshot version
          git add pom.xml
          git commit -m "Increment version to $NEW_VERSION [skip ci]"
          git push origin $(git rev-parse --abbrev-ref HEAD)

Bonus workflow

The CodeQL workflow analyzes your Java code to identify potential vulnerabilities and issues.

name: CodeQL

on:
  pull_request:
    branches: [ "main" ]
  workflow_dispatch:

jobs:
  analyze:
    name: Analyze
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: [ 'java' ]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven
          cache-dependency-path: '**/pom.xml'

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}

      - name: Autobuild
        uses: github/codeql-action/autobuild@v3

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{matrix.language}}"

Updated Dockerfile

### Build stage
FROM eclipse-temurin:21-jre-alpine AS builder

# Set the working directory inside the container
WORKDIR /tmp

# Copy the source code into the container
COPY target/*.jar app.jar

# Extract the layers
RUN java -Djarmode=layertools -jar app.jar extract

### Run stage
# Create a minimal production image
FROM eclipse-temurin:21-jre-alpine

# Set the working directory inside the container
WORKDIR /app

# Set the working directory inside the container
COPY --from=builder /tmp/dependencies/ ./
COPY --from=builder /tmp/snapshot-dependencies/ ./
COPY --from=builder /tmp/spring-boot-loader/ ./
COPY --from=builder /tmp/application/ ./

# Run the binary when the container starts
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

SpringBoot Web Service - Part 4 - Initial Configuration

vlaship — Sun, 05 Jan 2025 05:41:07 +0000

In this post, we'll explore how to configure OpenAPI in your Spring Boot application and add a convenient redirection from the root URL to the Swagger UI. This setup will improve your API documentation and make it more accessible to developers.

OpenAPI Bean Configuration

First, let's create a configuration class to customize our OpenAPI documentation:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.boot.info.GitProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI(GitProperties gitProperties) {
        return new OpenAPI()
                .info(new Info()
                        .title("Book Catalog API")
                        .description("REST API for managing a book catalog. Application version: "+ gitProperties.get("build.version"))
                        .version("1.0.0")
                        .contact(new Contact()
                                .name("Book Catalog Team")
                                .email("support@bookcatalog.com")
                                .url("https://github.com/vlaship/book-catalog"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT"))
                );
    }
}

This configuration creates a custom OpenAPI bean with basic information about your API. You can further customize this by adding more details, such as contact information, license, or external documentation.
We can use GitProperties to provide more details.

Root URL Redirection Controller

Next, let's create a controller to redirect users from the root URL to the Swagger UI:

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class OpenApiController {
    @GetMapping("/")
    public String index() {
        return "redirect:swagger-ui.html";
    }
}

This simple controller uses a @GetMapping for the root URL ("/") and redirects to the Swagger UI HTML page.

Updating `application.yaml`

This configuration file, often named application.yml, plays a crucial role in defining various aspects of your application's behavior.

spring:
  application:
    name: book-catalog
    version: '@project.version@'
  mvc:
    problemdetails:
      enabled: true
  threads:
    virtual:
      enabled: true

management:
  endpoints:
    web:
      exposure:
        include: '*'
  info:
    git:
      mode: full

server:
  port: 8888
  servlet:
    context-path: /${spring.application.name}
  error:
    whitelabel:
      enabled: false

The provided YAML configuration covers several key areas of your Spring Boot application:

Application Properties:

name: Defines the application's name, here set to book-catalog.

version: References a placeholder, likely populated during the build process, to specify the application's version.

Virtual Threads:

threads.virtual.enabled: true: Enables supporting virtual threads in Spring Boot.

MVC Configuration:

problemdetails.enabled: Enables detailed problem reports in the response body for exceptions.

Management Endpoints:

endpoints.web.exposure.include: '*':** Exposes all actuator endpoints for monitoring and management purposes.

info.git.mode: full: Provides detailed Git information in the /info endpoint.

Server Configuration:

port: Sets the port on which the server listens for incoming requests (default 8080, here set to 8888).

servlet.context-path: Defines the context path for the application, ensuring requests are routed correctly.

error.whitelabel.enabled: false: Disables the default whitelabel error page, allowing for more informative error messages during development.

Adding `banner.txt`

1. Create banner.txt file

Create a new file named banner.txt within the src/main/resources directory of your Spring Boot project.

2. Add service details to banner.txt

You can add any text or ASCII art to this file. Here's an example:


/////////////////////////////////////////////////////////////////
////
//// :: application name      :: ${spring.application.name}
//// :: application version   :: ${spring.application.version}
//// :: spring-boot version   :: ${spring-boot.version}
//// :: spring active profile :: ${spring.profiles.active:}
//// :: context-path          :: ${server.servlet.context-path}
//// :: server port           :: ${server.port}
////
/////////////////////////////////////////////////////////////////

This approach adds a professional touch to your application startup and provides valuable information at a glance.

Adding `Dockerfile`

### Build stage
# Builder maven
FROM maven:3.9.9-amazoncorretto-21-alpine AS builder

# Set the working directory inside the container
WORKDIR /tmp

# Copy the source code into the container
COPY pom.xml .
COPY src src/

# Build
RUN mvn clean package

# Extract the layers
RUN java -Djarmode=layertools -jar target/*.jar extract

### Run stage
# Create a minimal production image
FROM azul/zulu-openjdk-alpine:21-jre-headless

# Set the working directory inside the container
WORKDIR /app

# Set the working directory inside the container
COPY --from=builder /tmp/dependencies/ ./
COPY --from=builder /tmp/snapshot-dependencies/ ./
COPY --from=builder /tmp/spring-boot-loader/ ./
COPY --from=builder /tmp/application/ ./

# Run the binary when the container starts
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

Layer Extraction: Creating separate layers for dependencies, improving build efficiency and reducing image size updates.
Multi-stage Build: Utilizing a multi-stage build process to separate the build environment from the runtime environment, resulting in a smaller and more efficient final image.
Lightweight Base Image: Using a minimal base image like azul/zulu-openjdk-alpine:21-jre-headless to further reduce the image size.

This approach leads to faster builds, smaller image sizes, and improved overall performance for your Spring Boot application within a Docker container.

SpringBoot Web Service - Part 3 - Modifying pom.xml

vlaship — Sun, 05 Jan 2025 05:12:40 +0000

In this post, we'll explore how to configure a Maven project without using the Spring Boot parent POM. We'll add custom properties, dependencies, plugins, and build configurations to create a more flexible and tailored setup.

Removing Spring Boot Parent

First, remove the Spring Boot parent from your pom.xml:

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.1</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

Adding Custom Properties

Add the following properties to your pom.xml:

    <properties>
        <java.version>21</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <maven.compiler.release>${java.version}</maven.compiler.release>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

        <spring-boot-dependencies.version>3.4.1</spring-boot-dependencies.version>
        <springdoc.version>2.7.0</springdoc.version>
        <org.mapstruct.version>1.6.3</org.mapstruct.version>
        <git-commit-id-maven-plugin.version>9.0.1</git-commit-id-maven-plugin.version>
        <maven-compiler-plugin.version>3.13.0</maven-compiler-plugin.version>
    </properties>

Updating Dependencies

Include the following dependencies:

 <dependencies>
        <!-- spring -->
        <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>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>

        <!-- open api -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>${springdoc.version}</version>
        </dependency>

        <!-- pojo -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${org.mapstruct.version}</version>
        </dependency>

        <!-- tests -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

Adding Dependency Management

Since we're not using the Spring Boot parent, we need to manage dependencies ourselves:

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot-dependencies.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

Updating Build Plugins

Configure the necessary plugins in the <build> section:

    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${maven-compiler-plugin.version}</version>
                <configuration>
                    <parameters>true</parameters>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </path>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${org.mapstruct.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <goals>
                            <goal>build-info</goal>
                            <goal>repackage</goal>
                        </goals>
                        <configuration>
                            <layers>
                                <enabled>true</enabled>
                            </layers>
                        </configuration>
                    </execution>
                </executions>
                <version>${spring-boot-dependencies.version}</version>
            </plugin>
            <plugin>
                <groupId>io.github.git-commit-id</groupId>
                <artifactId>git-commit-id-maven-plugin</artifactId>
                <version>${git-commit-id-maven-plugin.version}</version>
                <executions>
                    <execution>
                        <id>get-the-git-infos</id>
                        <goals>
                            <goal>revision</goal>
                        </goals>
                        <phase>initialize</phase>
                    </execution>
                </executions>
                <configuration>
                    <failOnNoGitDirectory>false</failOnNoGitDirectory>
                    <failOnUnableToExtractRepoInfo>false</failOnUnableToExtractRepoInfo>
                    <generateGitPropertiesFile>true</generateGitPropertiesFile>
                    <generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
                    <includeOnlyProperties>
                        <includeOnlyProperty>^git.build.time$</includeOnlyProperty>
                        <includeOnlyProperty>^git.build.version$</includeOnlyProperty>
                        <includeOnlyProperty>^git.commit.id$</includeOnlyProperty>
                        <includeOnlyProperty>^git.commit.id.abbrev$</includeOnlyProperty>
                        <includeOnlyProperty>^git.branch$</includeOnlyProperty>
                        <includeOnlyProperty>^git.tags$</includeOnlyProperty>
                    </includeOnlyProperties>
                    <commitIdGenerationMode>full</commitIdGenerationMode>
                </configuration>
            </plugin>
        </plugins>
    </build>

This configuration provides a more flexible setup without relying on the Spring Boot parent POM. It includes custom properties, dependency management, and build plugins for compiling, processing annotations, adding Git information, and packaging the application. The git-commit-id-maven-plugin will add Git information to your build, which can be useful for tracking deployments and versions. The maven-compiler-plugin is configured to use MapStruct for annotation processing and enable parameter names in compiled classes

This setup gives you more control over your project's configuration while still leveraging the power of Spring Boot and other useful libraries.

SpringBoot Web Service - Part 2 - Preparing Using Spring Initializr

vlaship — Sun, 05 Jan 2025 04:49:16 +0000

Creating a Service Using Spring Boot and Maven

In this post, we'll create a simple service using Spring Boot and Maven. Let's walk through the steps to set up a project and add the necessary dependencies.

Step 1: Navigate to start.spring.io

Head over to start.spring.io, the official Spring Initializr, which helps generate Spring Boot applications with ease.

Step 2: Configure Your Project

Set up your project with the following configuration:

Project: Maven
Language: Java
Spring Boot Version: 3.4.1
Project Metadata: Fill in details like group, artifact, name, description, and package name according to your preferences. For example:
- Group: com.example
- Artifact: demo-service
- Name: DemoService
- Description: A simple demo service using Spring Boot.
- Package Name: com.example.demoservice
Packaging: jar
Java Version: 21

Step 3: Add Dependencies

Select the following dependencies to include in your project:

Lombok: For reducing boilerplate code (like getters, setters, etc.).
Spring Boot Actuator: To monitor and manage your application in production.
Validation: This is for input validation support.
Spring Web: To build web applications, including RESTful APIs.

Step 4: Generate and Download the Project

Click the "Generate" button to download a pre-configured project archive. Once downloaded, extract the contents to your local development environment.

Step 5: Import the Project

After downloading and unpacking the project into your desired folder:

Open your IDE of choice (e.g., IntelliJ IDEA, Eclipse, or VS Code).
Import the project as a Maven project.
Wait for Maven to resolve dependencies and build the project.

SpringBoot Web Service - Part 1 - Create Repository

vlaship — Sun, 05 Jan 2025 04:45:27 +0000

Creating a Repository on GitHub

In this post, we'll walk through the steps to create a repository on GitHub, whether you're a beginner or just need a refresher.

Step 1: Create a GitHub Account (If You Don't Have One)

If you don't already have a GitHub account, go to GitHub.com and sign up. It's free to get started!

Step 2: Create a New Repository

Once you're logged in:

Click on the "+" icon in the top-right corner of the page.
Select "New repository" from the dropdown menu.

Step 3: Fill in Repository Details

Repository Name: Choose a meaningful name for your project.
Description (Optional): Add a brief description of what the repository is for.
Initialize with a README: Check this box to create a README.md file, which introduces your project.
Add .gitignore: Use the dropdown to select a .gitignore template Java.

Step 4: Create the Repository

Click the "Create repository" button to finish. GitHub will take you to the new repository's main page.

Step 5: Next Steps

Now that your repository is ready, you can:

Clone it to your local machine.

   git clone https://github.com/your-username/your-repository-name.git