Maven POM Conventions

1. Overview

Every EMS Spring Boot service (admin-service, registration-portal, and future admin-portal) inherits from the same parent POM and exposes the same set of Maven profiles. Build variants (dev vs prod, with or without OTel, with or without OpenAPI docs, with or without TLS) are selected by profile activation — not by separate build configurations or modules.

This convention is inherited from JHipster. We keep it because it is mature, widely understood, documented by the generator, and has no concrete better alternative in our stack. If we ever find one, it’ll be a project-wide rethink; for now, follow the pattern.

This page documents what profiles exist, what each enables, and what a new service’s POM should look like.

See also: Jib Docker Build, Helm Chart Structure.

2. Parent POM

Coordinates: za.co.idealogic:event:1.3.x. Lives at [parent-pom/](../../../parent-pom/) in the workspace; GitHub repo named event.

The parent pins:

  • Spring Boot (currently 3.2.x baseline, tracked via JHipster 8.11’s BOM)

  • JHipster framework version (8.11.0)

  • Common plugin versions (Jib, liquibase, modernizer, checkstyle, git-commit-id, helm-maven-plugin)

  • Shared dependency management (Jackson, Mapstruct, Hazelcast, SpringDoc, dayjs stand-ins for the Java side)

Child POMs inherit via <parent>:

<parent>
    <groupId>za.co.idealogic</groupId>
    <artifactId>event</artifactId>
    <version>1.3.1</version>
    <relativePath/>  <!-- resolve from ~/.m2, not local relative path -->
</parent>

Bumping the parent is a workspace-level event — upgrade all consumers together.

3. Profile Inventory

Active profiles combine via comma: mvn -Pprod,api-docs,otlp package. Multiple simultaneous profiles is the normal case.

Profile Activates What it toggles

dev

Default (activated when no other profile given)

Liquibase auto-apply with faker data context, local application-dev.yml, verbose logging

prod

Explicit

Production application-prod.yml, Liquibase with contexts: prod, Jib image build, WebJAR assembly into static path

no-liquibase

Explicit

Skip Liquibase on startup (useful when schema is managed out-of-band)

api-docs

Explicit

Enables springdoc.api-docs.enabled=true so /v3/api-docs serves the spec

tls

Explicit

Activates application-tls.yml — configures server.ssl.* for HTTPS

otlp

Explicit

Pulls in opentelemetry-spring-boot-starter, configures OTLP exporter (see OpenTelemetry Configuration)

war

Explicit

Package as WAR instead of executable JAR (legacy; rarely used)

docker-compose

<activation> based on -f docker-compose/…

Pulls in docker-compose-defined local dependencies (MySQL, Keycloak, MailHog) — auto-activated by the docker compose workflow

local-mysql

Explicit

Overrides default H2 with local MySQL connection string

test (registration-portal)

Explicit

Enables e2e test dependencies (Gatling, Cucumber)

e2e (registration-portal)

Explicit

Cypress and headless runner setup

ide

Explicit

IDE-specific overrides (typically disabling annotation processors that IDEs handle themselves)

Typical production build: mvn -Pprod,api-docs,otlp package.

Typical CI test run: mvn -Papi-docs,test verify (the api-docs profile is required for OpenAPI spec extraction in test phase — see OpenAPI Contract Flow).

Typical dev run: ./mvnw (no explicit profile; dev activates by default).

4. Plugin Set

Every POM includes:

Plugin Purpose

jib-maven-plugin

Build container image without a Docker daemon — see Jib Docker Build

liquibase-maven-plugin

Schema migration; runs on startup by default, can be invoked explicitly for diff/generate-changelog

git-commit-id-maven-plugin

Emit git.properties into the classpath — powers /actuator/info and the startup banner’s commit display

properties-maven-plugin

Read property files at build time for resource filtering

modernizer-maven-plugin

Flags outdated Java API usage (optional; warn-level for now)

helm-maven-plugin (io.kokuwa.maven)

Build / lint / template the per-service Helm chart during the package phase — see Helm Chart Structure

maven-checkstyle-plugin

Code-style enforcement (inherited from parent)

Portals additionally include:

Plugin Purpose

frontend-maven-plugin

Download Node + npm, run npm install and npm run build during the generate-resources phase; the Angular build output lands in target/classes/static/

Current Node / npm versions (from registration-portal pom): Node 22.15.0, npm 11.3.0. Bump carefully; Node upgrades have broken JHipster webpack setups in the past.

5. Version Strategy

project.version is bumped at release:

  • 1.3.1 → 1.3.2-SNAPSHOT on develop after release

  • CI on develop builds -SNAPSHOT artefacts; deploys to dev/stage environments

  • mvn -B release:prepare release:perform (via GitHub Actions — see the gitflow release pipeline) cuts the release

application.version in the logged banner is derived from project.version. git.properties (from git-commit-id-maven-plugin) provides commit SHA.

For the OpenAPI spec (see OpenAPI Contract Flow), info.version is derived from project.version too — so bumping the POM version automatically bumps the API spec version.

6. New Service Checklist

When creating admin-portal (or any new service):

  1. Parent: <parent>za.co.idealogic:event:1.3.x</parent> with empty relativePath

  2. <artifactId> in event-* naming: event-admin-portal

  3. <packaging>jar</packaging>

  4. <properties>: <java.version>21</java.version>, <project.version>0.0.0-SNAPSHOT</project.version>, plus any service-specific properties

  5. <dependencies>: Spring Boot starter web, Hazelcast, Spring Session + Hazelcast, springdoc, the Spring Cloud Gateway MVC starter, OAuth2 client (for OIDC), parent-pom-provided commons

  6. <profiles> — copy the full set from registration-portal (reliable reference). Customise only where the service deviates; otherwise keep identical.

  7. <build><plugins> — copy the standard set from registration-portal.

  8. Jib configuration — bump the <to><image> name to docker.io/christhonie/event-admin-portal.

  9. Helm chart placeholder under src/main/helm/ — see Helm Chart Structure.

  10. bootstrap.yml + bootstrap-prod.yml under src/main/resources/config/ — see SpringApplication Bootstrap.

Template the service off registration-portal’s layout; it is the newest JHipster 8.11 output and closest to what admin-portal will look like.

7. Deviations Worth Noting

POM item Why it deviates from stock JHipster

Hazelcast-Hibernate-53 dependency (admin-service only)

L2 cache provider not in stock JHipster 8 output; pinned to match Hazelcast 5.x

opentelemetry-javaagent download to Jib extraDirectories (admin-service otlp profile)

Stock JHipster includes Micrometer integration but not the full OTel javaagent; we download and bake it into the image for auto-instrumentation

helm-maven-plugin from io.kokuwa.maven rather than com.deviceinsight

Better template support for our per-environment values files

git-commit-id-maven-plugin at io.github.git-commit-id (new groupId)

The old pl.project13.maven is abandoned; this is the maintained fork

Document deviations in the POM via XML comments. Future maintainers should know why something is non-stock.

8. Reference

File Role

parent-pom/pom.xml

Parent POM; dependency + plugin management

admin-service/pom.xml

Reference for monolithic service POM with full profile set

registration-portal/pom.xml

Reference for portal POM with frontend-maven-plugin integration

parent-pom/README.md

Any parent-specific upgrade notes

9. Related Documentation

10. Change History

Date Change

2026-04-24

Initial draft. Grounded in admin-service and registration-portal POMs.