Setup Java Spring Boot

This documentation was generated with the assistance of AI. Please report any inaccuracies.

End-to-end bootstrap for a brand-new Spring Boot service repository built on Domain-Driven Design and hexagonal (ports and adapters) architecture, realised as a Maven multi-module reactor. It interviews the user once, resolves every Spring Boot version and dependency id against the live Spring Initializr API, records the answers in a springboot-stack.yml manifest, and then delegates all file generation to seven sub-skills.

Purpose

iru-setup-java-springboot is the top-level entry point for starting a Spring Boot microservice from nothing. It is the interviewer and orchestrator of the Spring Boot family: no other skill in that family asks the user anything about the stack, because this one asks everything exactly once and writes the answers to a manifest the others read back.

Three things distinguish it from iru-setup-java-library-repository, the catalog’s other bootstrap orchestrator:

  • It imposes an architecture. The module layout (domain, application, infrastructure/, api/, boot, coverage), the direction dependencies may point, and the rule that every dependency version lives only in the root pom.xml are not options — they are what the skill exists to enforce.

  • It resolves the stack from a live API rather than from memory. Spring Boot renames starter artifacts across major versions (in Boot 4.x spring-boot-starter-web became spring-boot-starter-webmvc, the Testcontainers modules became testcontainers-<engine>, and every starter gained a spring-boot-starter-<x>-test companion), so the skill reads https://start.spring.io/metadata/client for the current version list and dependency catalogue, and fetches a reference pom.xml from https://start.spring.io/pom.xml for the exact artifact names. If that API is unreachable it stops rather than guessing.

  • It produces a deployable service, not a publishable library. There is no Maven Central publishing or GPG signing; instead there is a container image, OpenTofu infrastructure-as-code for AWS or Google Cloud, and deploy and undeploy workflows.

Java 21 is the enforced minimum, in maven.compiler.release, java.version, and a maven-enforcer-plugin requireJavaVersion rule — even though Spring Initializr’s own default javaVersion is currently lower.

Purpose group

Spring Boot Service Bootstrap

Invocation

/iru-setup-java-springboot

Inputs

All inputs are collected interactively; nothing is passed in via args. The skill is the top of the chain.

Argument Required Description Default

groupId, artifactId, version, base Java package, service description, developer name/email/organizationUrl

Yes

Free-text project-identity fields asked in plain conversation in Step 2. The artifactId becomes the prefix of every module’s own artifactId; the base package roots every module’s package.

version defaults to 0.0.1-SNAPSHOT

Spring Boot version

Yes

Confirmed via AskUserQuestion from the live Initializr catalogue, offering the current GA release as the recommendation. Pre-release entries are never offered as the default.

bootVersion.default from the API

Java version

Yes

Confirmed via AskUserQuestion, filtered to versions the Initializr accepts. Anything below 21 is refused.

21

Deployment platform

Yes

AskUserQuestion: Amazon Web Services or Google Cloud. Drives the OpenTofu layout, the dynamic-configuration recommendation, and the deploy workflows.

None — user must choose

Concurrency model

Yes

AskUserQuestion: non-reactive/blocking (Spring MVC), reactive (WebFlux/Netty), or both. Decides which starter every other technology resolves to, so it is settled before any technology choice.

Blocking is presented as the recommendation

Databases

No

Multi-select from MongoDB, Couchbase, relational (PostgreSQL or MariaDB), Elasticsearch, Neo4j, and Qdrant, each presented with the workload shape it suits. Every engine chosen also requires an index/migration tool (Flamingock, Liquibase and its MongoDB/Couchbase/Neo4j extensions, or Flyway).

None

Caches

No

Multi-select: Caffeine (local, per-node) and/or Redis (shared across replicas).

None

Spring Security

No

Yes/no, plus whether the service validates incoming JWTs (oauth2-resource-server), initiates login flows (oauth2-client), or both.

No

Spring Cloud Stream / Kafka

No

Yes/no, plus the directions needed (produce, consume, or both). AVRO is the message format, and an AsyncAPI specification alongside the schemas documents the topics carrying them.

No

REST server, gRPC server, GraphQL server

No

Yes/no each. All three are contract-first: specs live in apis/ and code is generated from them. GraphQL additionally needs a web transport starter alongside spring-boot-starter-graphql, which carries none of its own.

No

REST clients, gRPC clients, GraphQL clients

No

A name per downstream service; each becomes an infrastructure/clients/<name> module and an apis/ spec directory. One module per service, with a generator execution per protocol, when a service is reached over more than one.

None

API mocking tool

Only if a client was named

Which mock stands in for the downstream services in integration tests and local runs — Microcks whenever any gRPC or GraphQL client exists (it mocks all three protocols from the same contracts in one container), WireMock for a REST-only service (lighter, with a wiremock-grpc-extension available if gRPC arrives later). Recorded as stack.apiMock and acted on by Setup Java Spring Boot Testcontainers.

Microcks with gRPC or GraphQL, WireMock for REST-only

Logging, metrics, tracing

No

Asked individually; all three recommended. Metrics adds Prometheus/Grafana containers for local development.

Recommended on

Spring AI

No

Yes/no. If yes: the LLM providers (offered from the live catalogue), an optional vector store, and optional MCP server/client support. The user is warned first that this requires a paid provider subscription.

No

Dynamic configuration

Yes

AskUserQuestion: Kubernetes ConfigMaps/Secrets, AWS Secrets Manager, Spring Cloud Config Server, or none. The recommendation follows from the deployment platform.

Derived from the platform choice

Other Initializr dependencies

No

Anything else from the live catalogue, by id or name, with a warning that entries outside the groups above are typically less relevant and some actively conflict with the contract-first hexagonal shape.

None

Outputs

  • springboot-stack.yml at the repository root — the manifest recording the resolved identity and every technology choice, with container image tags pinned. Meant to be committed; read by every sub-skill and later by iru-update-java-springboot-documentation.

  • The full Maven reactor: root pom.xml plus one pom per module (via iru-setup-java-springboot-pom).

  • The hexagonal source tree — ports, adapters, use cases, the @SpringBootApplication class, per-profile configuration, migration changelogs, and an ArchUnit test enforcing the dependency direction (via iru-setup-java-springboot-modules).

  • The apis/ contract tree, the OpenAPI/protobuf/GraphQL-SDL/AVRO generator wiring, and the AsyncAPI specification and documentation generators for messaging (via iru-setup-java-springboot-apis).

  • compose.yaml and the Testcontainers integration-test harness (via iru-setup-java-springboot-testcontainers).

  • An infra/ OpenTofu configuration for the chosen cloud (via iru-setup-java-springboot-platform).

  • build.yml, deploy.yml, and undeploy.yml GitHub Actions workflows (via iru-setup-java-springboot-github-workflows).

  • An Antora documentation site with Mermaid and Kroki and the full service page set (via iru-update-java-springboot-documentation).

  • Repository-level supporting files: .gitignore, README.md, CHANGELOG.md, checkstyle.xml, and optionally LICENSE.

  • A final report consolidating every secret and variable that must be supplied out-of-band, every open gap, and the result of the three verification builds.

Execution flow

flowchart TD A["Start /iru-setup-java-springboot"] --> B["Step 0: Check pom.xml / springboot-stack.yml\nand verify prerequisites"] B -- pom.xml exists, user chooses stop --> STOP[Stop; report] B -- ok --> C["Step 1: Fetch Initializr metadata;\nconfirm Boot version and Java version (21 minimum)"] C -- API unreachable --> STOP2["Stop — never fall back\nto hardcoded versions"] C --> D["Step 2: Collect project identity;\ninfer repository info from git"] D --> E["Step 3: Deployment platform (AWS/GCP)\nand concurrency model"] E --> F["Step 4: Choose technologies\n(databases, caches, security, Kafka, servers,\nclients, observability, AI, dynamic config)"] F --> G["Step 5: Confirm the whole plan"] G -- corrections --> F G -- confirmed --> H["Step 6: Write springboot-stack.yml"] H --> I["Step 7: Fetch the reference pom from Initializr"] I -- invalid id / incompatible version --> F I --> J["Step 8: Delegate to 7 sub-skills in order,\neach via iru-isolated-skill-executor"] J -- pom sub-skill did not write the root pom --> STOP3["Stop — no reactor to attach to"] J --> K["Step 9: Supporting files\n(.gitignore, README, CHANGELOG, checkstyle.xml)"] K --> L["Step 10: Verify — clean verify -DskipTests,\ntest, verify (via iru-gate-runner)"] L --> M["Step 11: Report, secrets table,\nand review warnings"]

Dependencies

Invokes

Each of the following is invoked via the iru-isolated-skill-executor agent rather than a direct Skill call, in this order — every sub-skill reads springboot-stack.yml and the filesystem directly, so only a short completion summary needs to come back:

  • Setup Java Spring Boot Poms — Step 8, first: the root reactor pom and every module pom. Also receives the path to the Initializr reference pom saved in Step 7. If this reports that the root pom was not written, the whole run stops.

  • Setup Java Spring Boot Modules — Step 8: the source tree, ports, adapters, profiles, and the ArchUnit test. Runs after the poms because it writes sources into modules rather than creating them.

  • Setup Java Spring Boot APIs — Step 8: the apis/ contracts, the code generators, and the AsyncAPI documentation generators. Runs after the modules because generated sources need a module to land in.

  • Setup Java Spring Boot Testcontainers — Step 8: compose.yaml and the integration-test harness. Runs after the APIs because the compose stack must know whether a schema registry is needed.

  • Setup Java Spring Boot Platform — Step 8: the OpenTofu configuration.

  • Setup Java Spring Boot GitHub Workflows — Step 8: the build, deploy, and undeploy workflows. Runs late because it surveys what is actually on disk.

  • Update Java Spring Boot Documentation — Step 8, last: the Antora site and the service page set, derived from the finished codebase.

In Step 9 it also invokes, if available, Setup Java Gitignore, Setup Readme, and Setup Changelog for the repository-level files the Spring Boot sub-skills don’t own. It additionally recommends — but does not invoke — Check License for license headers and Check Security for secret scanning, the latter specifically if an LLM API token may ever have been committed.

Invoked by

None — iru-setup-java-springboot is a top-level entry point; no other skill in this catalog invokes it.

Related agents

  • iru-isolated-skill-executor — spawned once per sub-skill in Step 8, so seven sub-skills' template expansion, file reads, and build output don’t accumulate in this orchestrator’s context over a single bootstrap run.

  • iru-gate-runner — spawned for each of Step 10’s three Maven verification runs, so a multi-module Maven log never lands in this conversation.

Source

SKILL.md on GitHub — the file this page was generated from.