Build and Packaging

This document provides a comprehensive guide to the build, packaging, and deployment artifact structure for the IT Ticketing Service. It is intended for developers responsible for building, maintaining, and deploying the application.

The project uses Apache Maven as its build automation and dependency management tool. The entire build process is defined in the pom.xml file at the root of the project.

Prerequisites

Before building the application, ensure the following prerequisites are met:

• Java 17 or higher: The application is built and runs on Java 17.
• Maven 3.6+: Required for building the application and managing dependencies.

Maven Build

The pom.xml file is the cornerstone of the project's build configuration. It leverages the spring-boot-starter-parent to inherit sensible defaults and manage dependency versions, ensuring consistency and reducing boilerplate configuration.

pom.xml Configuration

The project's core identity and dependencies are defined in pom.xml.

• Parent POM: The project inherits from spring-boot-starter-parent, which simplifies dependency management and plugin configuration.

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

• Project Coordinates: The generated artifact will be named based on these coordinates: it-ticketing-service-1.0.0.jar.

  <groupId>com.slalom.demo</groupId>
  <artifactId>it-ticketing-service</artifactId>
  <version>1.0.0</version>

Dependency Management

Dependencies are managed via the <dependencies> block. The use of Spring Boot "starters" (e.g., spring-boot-starter-web) pulls in a curated set of transitive dependencies required for specific functionalities.

Key dependencies include:

• spring-boot-starter-web: For building RESTful APIs with Spring MVC and an embedded Tomcat server.
• spring-boot-starter-data-jpa: For database interaction using Spring Data and JPA.
• spring-boot-starter-validation: For server-side data validation using Jakarta Bean Validation.
• spring-boot-starter-amqp: For integration with RabbitMQ.
• spring-boot-starter-actuator: For production-ready features including health checks, metrics, and monitoring endpoints.
• mysql-connector-j: The JDBC driver for MySQL, scoped to runtime as it's only needed when the application is running, not during compilation.
• lombok: Used to reduce boilerplate code. It is marked as <optional>true</optional> and is excluded from the final JAR, as it's a compile-time tool.

Build Lifecycle Phases

The build process follows the standard Maven lifecycle. The most common command is:

mvn clean package

• clean: This phase removes the target directory, ensuring a fresh build by deleting any previously compiled code and packaged artifacts.
• package: This phase compiles the source code, runs any tests, and packages the application into its distributable format, which in this case is an executable JAR file.

Plugin Configuration

The <build> section of the pom.xml configures plugins essential for the build process.

1. maven-compiler-plugin: This plugin is configured to enable Lombok's annotation processing during compilation. Without this, annotations like @Data or @Builder would not be processed, leading to compilation errors.

   <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-compiler-plugin</artifactId>
       <configuration>
           <annotationProcessorPaths>
               <path>
                   <groupId>org.projectlombok</groupId>
                   <artifactId>lombok</artifactId>
                   <version>1.18.34</version>
               </path>
           </annotationProcessorPaths>
       </configuration>
   </plugin>

2. spring-boot-maven-plugin: This is the key plugin for creating a runnable Spring Boot application. It repackages the standard JAR into an executable "fat JAR" that includes all dependencies.

   <plugin>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-maven-plugin</artifactId>
       <configuration>
           <excludes>
               <exclude>
                   <groupId>org.projectlombok</groupId>
                   <artifactId>lombok</artifactId>
               </exclude>
           </excludes>
       </configuration>
   </plugin>

   Gotcha: The configuration explicitly excludes the Lombok dependency from the final executable JAR. This is a best practice, as Lombok is a compile-time-only tool and is not needed at runtime. Including it could unnecessarily increase the artifact size and potential attack surface.

Building the JAR

Building the application artifact is a straightforward process using a single Maven command.

mvn clean package Command

To produce the deployment artifact, navigate to the project's root directory and run:

# Cleans the project and builds the executable JAR
mvn clean package

This command will compile the code, run unit tests, and create the final JAR file.

JAR File Location

Upon a successful build, the executable JAR file will be located in the target/ directory. Based on the pom.xml, the file will be named:

target/it-ticketing-service-1.0.0.jar

Embedded Tomcat Server

The spring-boot-starter-web dependency includes an embedded Tomcat server by default. The spring-boot-maven-plugin ensures that this server is packaged within the JAR, making the application self-contained and runnable without needing an external servlet container. For more details on running the application, see the Installation Guide.

Build Profiles

While the current pom.xml does not define explicit Maven build profiles (e.g., <profile> blocks for dev and prod), the application leverages Spring Boot's robust profile mechanism for managing environment-specific configurations.

This is achieved by creating profile-specific properties files in src/main/resources/. For example:

• application-dev.properties: Contains settings for the development environment, such as connecting to a local database.
• application-prod.properties: Contains settings for the production environment, such as production database credentials and higher logging levels.

A profile can be activated at runtime using a command-line argument:

java -jar -Dspring.profiles.active=prod target/it-ticketing-service-1.0.0.jar

This approach is preferred over Maven profiles for application configuration as it decouples the build artifact from the target environment. The same JAR can be promoted across environments simply by changing the active Spring profile.

Deployment Artifacts

The primary deployment artifact is the executable JAR file generated by the build process.

Executable JAR Structure

The it-ticketing-service-1.0.0.jar is a "fat JAR" or "uber JAR". It follows a specific structure defined by Spring Boot:

• BOOT-INF/classes/: Contains the compiled application classes (e.g., controllers, services, repositories).
• BOOT-INF/lib/: Contains all the project dependencies as individual JAR files (e.g., spring-web-3.2.4.jar, mysql-connector-j-8.4.0.jar).
• META-INF/: Contains standard JAR manifest information. The MANIFEST.MF file specifies the main class (org.springframework.boot.loader.launch.JarLauncher) that bootstraps the application.
• org.springframework.boot.loader.*: Contains the Spring Boot loader classes that know how to load the nested classes and libraries from BOOT-INF/.

This structure allows the application to be run with a simple java -jar command.

Configuration Externalization

The application is designed for configuration to be externalized, a core principle of cloud-native applications. The default configuration is bundled inside the JAR in BOOT-INF/classes/application.properties.

However, these properties can be overridden without rebuilding the JAR using several mechanisms, in order of precedence (lowest to highest):

1. Properties file inside the JAR (application.properties).
2. Properties file outside the JAR, in the same directory (./config/application.properties or ./application.properties).
3. Command-line arguments (--spring.datasource.url=...).
4. Environment variables (SPRING_DATASOURCE_URL=...).

This flexibility is critical for deployment in modern environments, such as containers or cloud platforms. For more information, see the guides on Docker Deployment and Cloud Migration.

Version Management

The application version is managed in the pom.xml file:

<version>1.0.0</version>

This version is used in the name of the final JAR artifact. It is recommended to use a semantic versioning scheme and to leverage CI/CD pipelines to automatically increment versions or append build metadata (e.g., 1.0.0-SNAPSHOT or 1.0.0+build.123).