Developing and compiling your IBM Enterprise Build of Quarkus applications with Apache Maven

As an application developer, you can use IBM Enterprise Build of Quarkus to create microservices-based applications written in Java that run on OpenShift Container Platform and serverless environments. Applications compiled to native executables have small memory footprints and fast startup times.

Use the Quarkus Apache Maven plugin to create a IBM Enterprise Build of Quarkus project.

Note: Where applicable, alternative instructions for using the Quarkus command-line interface (CLI) are provided. The Quarkus CLI is intended for development purposes, including tasks such as creating, updating, and building Quarkus projects. However, IBM does not support using the Quarkus CLI in production environments.

Prerequisites

You have installed OpenJDK 17, 21, or 25.
- To download Red Hat build of OpenJDK, log in to the Red Hat Customer Portal and go to the "Software Downloads" page.
You have set the JAVA_HOME environment variable to specify the location of the Java SDK.
You have installed Apache Maven 3.9.12.
- To download Maven, go to the "Apache Maven Project" website.

About IBM Enterprise Build of Quarkus

IBM Enterprise Build of Quarkus is a Kubernetes-native Java stack optimized for containers and Red Hat OpenShift Container Platform. Quarkus is designed to work with popular Java standards, frameworks, and libraries such as Eclipse MicroProfile, Eclipse Vert.x, Apache Camel, Apache Kafka, Hibernate ORM with Jakarta Persistence, and Jakarta REST.

As a developer, you can choose the Java frameworks you want for your Java applications, which you can run in Java Virtual Machine (JVM) mode or compile and run in native mode. Quarkus provides a container-first approach to building Java applications. The container-first approach facilitates the containerization and efficient execution of microservices and functions. For this reason, Quarkus applications have a smaller memory footprint and faster startup times.

Quarkus also optimizes the application development process with capabilities such as unified configuration, automatic provisioning of unconfigured services, live coding, and continuous testing, which provides instant feedback on your code changes.

For information about how IBM Enterprise Build of Quarkus differs from the Quarkus community version, see "Differences between the Quarkus community version and IBM Enterprise Build of Quarkus" in Additional resources.

Additional resources

Differences between the Quarkus community version and IBM Enterprise Build of Quarkus

Apache Maven and IBM Enterprise Build of Quarkus

Apache Maven is a distributed build automation tool that is used in Java application development to create, manage, and build software projects.

Maven repositories

A Maven repository stores Java libraries, plugins, and other build artifacts. Maven Central is the default public repository; however, repositories can also be private and internal within a company, allowing for the sharing of common artifacts among development teams. Repositories are also available from third parties.

You can use the IBM-hosted Maven repository with your Quarkus projects.

You declare project dependencies in the pom.xml file and configure access to the Maven repositories globally in your $HOME/.m2/settings.xml file. This helps ensure that your projects use certified IBM Enterprise Build of Quarkus artifacts without needing repository details to be included in the POM file of each project.

Maven plugins

Maven plugins are defined parts of a POM file that run one or more tasks. IBM Enterprise Build of Quarkus applications use the following Maven plugins:

Quarkus Maven plugin (quarkus-maven-plugin): Enables Maven to create Quarkus projects, packages your applications into JAR files, and provides a dev mode.
Maven Surefire plugin (maven-surefire-plugin): When Quarkus enables the test profile, the Maven Surefire plugin is used during the test phase of the build lifecycle to run unit tests on your application. The plugin generates text and XML files that contain the test reports.

Additional resources

Configure the Maven settings.xml file for the online repository

To use the IBM-hosted Quarkus repository with your Quarkus Maven project, configure the settings.xml file for your user. The configuration defines the Quarkus repository as a Maven profile and activates it so Maven can resolve Quarkus dependencies during builds.

Note: When you configure the repository by modifying the Maven settings.xml file, the changes apply to all of your Maven projects. If you want to apply the configuration to a specific project only, use the -s option and specify the path to the project-specific settings.xml file.

Procedure

Open the Maven $HOME/.m2/settings.xml file in a text editor or an integrated development environment (IDE).

Note: If no settings.xml file is present in the $HOME/.m2/ directory, copy the settings.xml file from the $MAVEN_HOME/conf/ directory into the $HOME/.m2/ directory.

Add the following Maven profile, which defines the IBM-hosted Quarkus repository, to the <profiles> element of the settings.xml file:

<profile>
  <id>ibm-enterprise-maven-repository</id>
  <repositories>
    <repository>
      <id>ibm-enterprise-maven-repository</id>
      <url>https://maven.repository.ibm.com/releases/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>ibm-enterprise-maven-repository</id>
      <url>https://maven.repository.ibm.com/releases/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>
</profile>

Add the following lines to the <activeProfiles> element of the settings.xml file and save the file.

<activeProfiles>
  <activeProfile>ibm-enterprise-maven-repository</activeProfile>
</activeProfiles>

Verification

Run mvn help:effective-settings. The output lists the Quarkus repository profile under <profiles> and shows it as active under <activeProfiles>.

Additional resources

Create a IBM Enterprise Build of Quarkus project on the command line

Use the IBM Enterprise Build of Quarkus Maven plugin on the command line to create a Quarkus project by providing attributes and values on the command line or by using the plugin in interactive mode. You can also create a Quarkus project by using the Quarkus command-line interface (CLI). The resulting project includes the following elements:

The Maven structure
An associated unit test
A landing page that is accessible on http://localhost:8080 after you start the application
Example Dockerfile files for JVM and native mode in src/main/docker
The application configuration file

Note: By default, the Quarkus Maven plugin uses the latest preferred quarkus-bom version. The quarkus-bom file aggregates extensions so that you can reference them from your applications to align the dependency versions. When you are offline, the Quarkus Maven plugin uses the latest preferred version of the quarkus-bom that it previously pulled from the Maven repository.

Prerequisites

You have installed OpenJDK 17, 21, or 25.
- To download Red Hat build of OpenJDK, log in to the Red Hat Customer Portal and go to Software Downloads.
You have set the JAVA_HOME environment variable to specify the location of the Java SDK.
You have installed Apache Maven 3.9.12.
- To download Maven, go to the Apache Maven Project website.

Optional: You have installed the Quarkus command-line interface (CLI), which is one of the methods you can use to create a Quarkus project. For more information, see Installing the Quarkus CLI.

Note: The Quarkus CLI is intended for development purposes, including tasks such as creating, updating, and building Quarkus projects. However, IBM does not support using the Quarkus CLI in production environments.

Procedure

In a command terminal, enter the following command to verify that Maven is using OpenJDK 17, 21, or 25 and that the Maven version is 3.9.12:
```
mvn --version
```
If the preceding command does not return OpenJDK 17, 21, or 25, add the path to OpenJDK 17, 21, or 25 to the PATH environment variable and enter the preceding command again.

To create a project, use one of the following methods:

Use the Quarkus Maven plugin. Enter the following command:

mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.33.1.redhat-00006:create \
    -DprojectGroupId=<project_group_id> \
    -DprojectArtifactId=<project_artifact_id> \
    -DplatformGroupId=com.redhat.quarkus.platform \
    -DplatformArtifactId=quarkus-bom \
    -DplatformVersion=3.33.1.redhat-00006
    -DpackageName=getting.started

In this command, replace the following values:

<project_group_id>: A unique identifier of your project
<project_artifact_id>: The name of your project and your project directory

Create the project in interactive mode:

mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.33.1.redhat-00006:create

When prompted, enter the required attribute values.

Note: You can also create your project by using the default values for the project attributes by entering the following command:

mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.33.1.redhat-00006:create -B

Use the Quarkus CLI. Enter the following command:
```
quarkus create app my-groupId:my-artifactId --package-name=getting.started
```
- You can also get the list of available options with:
  quarkus create app --help

Create a IBM Enterprise Build of Quarkus project by configuring the `pom.xml` file

You can use an existing Maven project to create a Quarkus project by configuring the Maven pom.xml file.

Procedure

Open the pom.xml file in a text editor.

Add the configuration properties that contain the following items:

The Maven Compiler plugin version
The Quarkus BOM groupID, artifactID, and version
The Maven Surefire plugin version
The skipITs property

<properties>
    <compiler-plugin.version>3.15.0</compiler-plugin.version>
    <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
    <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
    <quarkus.platform.version>3.33.1.redhat-00006</quarkus.platform.version>
    <surefire-plugin.version>3.5.4</surefire-plugin.version>
    <skipITs>true</skipITs>
</properties>

Add the Quarkus GAV (group, artifact, version) and use the quarkus-bom file to omit the versions of the different Quarkus dependencies:

<dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>${quarkus.platform.artifact-id}</artifactId>
        <version>${quarkus.platform.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

Add the Quarkus Maven plugin, the Maven Compiler plugin, and the Maven Surefire plugin:

<build>
    <plugins>
        <plugin>
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-maven-plugin</artifactId>
            <version>${quarkus.platform.version}</version>
            <extensions>true</extensions>
        </plugin>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>${compiler-plugin.version}</version>
            <configuration>
                <parameters>true</parameters>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${surefire-plugin.version}</version>
            <configuration>
                <argLine>@{argLine}</argLine>
                <systemPropertyVariables>
                    <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                    <maven.home>${maven.home}</maven.home>
                </systemPropertyVariables>
            </configuration>
        </plugin>
    </plugins>
</build>

Note: The maven-surefire-plugin runs the unit tests for your application.

Optional: To build a native application, add a specific native profile that includes the maven-failsafe-plugin:

<build>
    <plugins>
        ...
        <plugin>
            <artifactId>maven-failsafe-plugin</artifactId>
            <version>${surefire-plugin.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>integration-test</goal>
                        <goal>verify</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <argLine>@{argLine}</argLine>
                <systemPropertyVariables>
                    <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                    <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                    <maven.home>${maven.home}</maven.home>
                </systemPropertyVariables>
            </configuration>
        </plugin>
    </plugins>
</build>
...
<profiles>
    <profile>
        <id>native</id>
        <activation>
            <property>
                <name>native</name>
            </property>
        </activation>
        <properties>
            <skipITs>false</skipITs>
            <quarkus.native.enabled>true</quarkus.native.enabled>
        </properties>
    </profile>
</profiles>

Tests that include IT in their names and contain the @QuarkusIntegrationTest annotation are run against the native executable.
For more details about how native mode differs from Java virtual machine (JVM) mode, see JVM and native building modes in the "Build your first application" guide.

Create the Getting started project by using code.quarkus.ibm.com

You can use the code.quarkus.ibm.com application to generate a Quarkus Maven project and automatically add and configure the extensions that you want to use in your application. In addition, code.quarkus.ibm.com automatically manages the configuration parameters that are required to compile your project into a native executable.

You can generate a Quarkus Maven project, including the following activities:

Specifying basic details about your application
Choosing the extensions that you want to include in your project
Generating a downloadable archive with your project files
Using custom commands for compiling and starting your application

Prerequisites

You have a web browser.
A Java 17, 21, or 25 compatible JVM installed. For example: Red Hat build of OpenJDK, an Adoptium-provided JDK, such as Eclipse Temurin, or an IBM distribution of OpenJDK, such as IBM Semeru Certified Edition.
- Download your preferred JVM:
  - Download Red Hat build of OpenJDK from the Red Hat Customer Portal Software Downloads page.
  - Download an Eclipse Temurin distribution from the Adoptium home page.
  - Download IBM Semeru from the IBM Semeru Runtimes page.
- Set the JAVA_HOME environment variable to the Java SDK installation location.
Apache Maven 3.9.12 installed. For information about installing Apache Maven, see the Apache Maven Project website.
The IBM-hosted Quarkus repository configured in the $HOME/.m2/settings.xml file.

Procedure

On your web browser, go to https://code.quarkus.ibm.com.

From the list of available versions, the code.quarkus.ibm.com application selects the latest release of IBM Enterprise Build of Quarkus by default.

Note: code.quarkus.ibm.com uses the latest release of IBM Enterprise Build of Quarkus, which is the preferred option. However, after generating your project, you can manually change to an earlier BOM version in the pom.xml file if necessary, but the best practice is to keep the default.

Specify basic details about your project:
1. Enter a group name for your project. The name format follows the Java package naming convention; for example, org.acme.
2. Enter a name for the Maven artifacts generated by your project, such as code-with-quarkus.
3. Select the build tool you want to use to compile and start your application. The build tool that you choose determines the following setups:
  - The directory structure of your generated project
  - The format of configuration files that are used in your generated project
  - The custom build script and command for compiling and starting your application that code.quarkus.ibm.com displays for you after you generate your project
    
    Note: IBM provides support for using code.quarkus.ibm.com to create Quarkus Maven projects only.
Specify additional details about your application project:
1. To display the fields that contain further application details, select More options.
2. Enter a version you want to use for artifacts generated by your project. The default value of this field is 1.0.0-SNAPSHOT. Using semantic versioning is preferred; however, you can choose to specify a different versioning type.
3. Select whether you want code.quarkus.ibm.com to add starter code to your project. When you add extensions that are marked with "STARTER-CODE" to your project, you can enable this option to automatically create example class and resource files for those extensions when you generate your project. However, this option does not affect your generated project if you do not add any extensions that provide example code.

Select the extensions that you want to use. The Quarkus application includes the extensions you select as dependencies. The Quarkus platform also ensures these extensions are compatible with future versions.

Important: Do not use the quarkus-rest and the quarkus-resteasy extensions in the same project. Both provide similar capabilities, but they differ significantly in implementation and behavior. Use quarkus-rest instead.

The quark icon () next to an extension indicates that the extension is part of the IBM Enterprise Build of Quarkus platform release. IBM prefers using extensions from the same platform because they are tested and verified together, making them easier to use and upgrade.

For extensions marked with "STARTER-CODE", you can enable the option to generate starter code automatically.

Screenshot of the list of extensions at the code.quarkus.ibm.com site that you can add to your project

To confirm your choices, select Generate your application. After generation, a dialog box displays the following items:
- A link to download the archive that contains your generated project
- A command that you can use to compile and start your application
To save the archive with the generated project files to your machine, select Download the ZIP.
Extract the contents of the archive.

Verification

Check the extracted structure and verify the pom.xml file is present in the root directory of your generated project.

Start the application in dev mode. Use either Apache Maven or the Maven wrapper:

mvn quarkus:dev

./mvnw quarkus:dev

The following extract shows an example of the expected output:

INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, rest, smallrye-context-propagation, vertx]

Configure the Java compiler

By default, the Quarkus Maven plugin passes compiler flags to javac command from maven-compiler-plugin.

Procedure

To customize the compiler flags used in development mode, add a configuration section to the plugin block and set the compilerArgs property. You can also set source, target, and jvmArgs. For example, to pass -verbose to the Java virtual machine (JVM) and javac commands, add the following configuration:

<plugin>
  <groupId>com.redhat.quarkus.platform</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <version>${quarkus.platform.version}</version>

  <configuration>
    <source>${maven.compiler.source}</source>
    <target>${maven.compiler.target}</target>
    <compilerArgs>
      <arg>-verbose</arg>
    </compilerArgs>
    <jvmArgs>-verbose</jvmArgs>
  </configuration>

  ...
</plugin>

Install and manage extensions

In IBM Enterprise Build of Quarkus, you can use extensions to expand your application’s functionality and configure, boot, and integrate a framework into your application. This procedure shows you how to find and add extensions to your Quarkus project.

Prerequisites

You have created a Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which is one of the methods you can use to manage your Quarkus extensions. For more information, see Installing the Quarkus CLI.

Procedure

Navigate to your Quarkus project directory.
List all the available extensions in one of the following ways:
- Using Maven:
  ./mvnw quarkus:list-extensions
- Using the Quarkus CLI:
  quarkus extension --installable
Add an extension to your project by using one of the following methods:
- Using Maven, enter the following command where <extension> is the group, artifact, and version (GAV) of the extension that you want to add:
  ./mvnw quarkus:add-extension -Dextensions="<extension>"
  For example, to add the Agroal extension, enter the following command:
  ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-agroal"
- Using the Quarkus CLI, enter the following command where <extension> is the group, artifact, and version (GAV) of the extension that you want to add:
  quarkus extension add '<extension>'
To search for a specific extension, enter the extension name or partial name after -Dextensions=. The following example searches for extensions that contain the text agroal in the name:
```
./mvnw quarkus:add-extension -Dextensions=agroal
```
This command returns the following result:
```
[SUCCESS] ✅  Extension io.quarkus:quarkus-agroal has been installed
```
Similarly, with the Quarkus CLI, you might enter:
```
quarkus extension add 'agroal'
```

Import a Quarkus project into Eclipse

Import a Quarkus Maven project into Red Hat CodeReady Studio or Eclipse to develop the project with editor features such as code completion, navigation, and refactoring. CodeReady Studio extends Eclipse with additional tooling for cloud-native and Red Hat middleware development.

Prerequisites

You have a Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which you can use to start your project in dev mode. For more information, see Installing the Quarkus CLI.

Procedure

In CodeReady Studio or Eclipse, click File > Import.
Select Maven > Existing Maven Project.
Select the root location of the project. A list of the available modules appears.
Select the generated project, and click Finish.
Compile and start your application in one of the following ways:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev

Verification

The project loads as a Maven project.

Import a Quarkus project into IntelliJ IDEA

Import a Quarkus Maven project into IntelliJ IDEA to develop the project with editor features such as code completion, navigation, and refactoring. IntelliJ IDEA Ultimate includes built-in Quarkus support; for Community Edition, install the Quarkus plugin from the JetBrains marketplace.

Prerequisites

You have a Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which you can use to start your project in dev mode. For more information, see Installing the Quarkus CLI.

Procedure

In IntelliJ IDEA, complete one of the following tasks:
- Select File > New > Project From Existing Sources.
- On the Welcome page, select Import project.
Select the project root directory.
Select Import project from external model, and then select Maven.
Review the options, and then click Next.
Click Create.
Compile and start your application in one of the following ways:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev

Verification

The project loads as a Maven project.

Import a Quarkus project into Apache NetBeans

Import a Quarkus Maven project into Apache NetBeans to develop the project with editor features such as code completion, navigation, and refactoring. Apache NetBeans includes Maven support natively, so no additional plugin is required.

Prerequisites

You have a Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which you can use to start your project in dev mode. For more information, see Installing the Quarkus CLI.

Procedure

Select File > Open Project.
Select the project root directory.
Click Open Project.
Compile and start your application in one of the following ways:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev

Verification

The project loads as a Maven project.

Open a Quarkus project in Visual Studio Code

Open a Quarkus Maven project in Visual Studio Code to develop the project with editor features such as code completion, navigation, and refactoring. Visual Studio Code recognizes Maven projects automatically when the Java Extension Pack is installed.

Prerequisites

You have a Quarkus Maven project.
Optional: You have installed the Quarkus command-line interface (CLI), which you can use to start your project in dev mode. For more information, see Installing the Quarkus CLI.

Procedure

Install the Java Extension Pack.
In Visual Studio Code, open your project directory.
Compile and start your application in one of the following ways:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev

Verification

Visual Studio Code recognizes the project as a Maven project.

Configure the IBM Enterprise Build of Quarkus project output

Before you build your application, you can control the build command output by changing the default values of the properties in the application.properties file.

Prerequisites

You have created a Quarkus Maven project.

Procedure

Go to the {project}/src/main/resources folder, and open the application.properties file in a text editor.

Add the properties that you want to change and save the file.

Table 1. Properties that you can change
Property	Description	Type	Default
`quarkus.native.enabled`	Enables native image generation. When set to `true`, the application is compiled into a native executable.	boolean	`false`
`quarkus.native.sources-only`	Generates only the native image sources without building the final native executable.	boolean	`false`
`quarkus.package.main-class`	Specifies the entry point of the application. In most cases, you must change this value.	string	`io.quarkus.runner.GeneratedMain`
`quarkus.package.jar.enabled`	Determines whether to build a JAR file. Set to `false` to prevent JAR creation.	boolean	`true`
`quarkus.package.jar.type`	Defines the type of JAR to build. Supported values are `fast-jar` (default), `uber-jar`, `mutable-jar`, and `legacy-jar` (deprecated). To prevent JAR generation entirely, set `quarkus.package.jar.enabled=false`.	string	`fast-jar`
`quarkus.package.type` (deprecated)	Deprecated. * Use `quarkus.package.jar.type` to configure the JAR type. * For native builds, set `quarkus.native.enabled` to `true`. * For native sources builds, also set `quarkus.native.sources-only` to `true`. * JAR building can be disabled by setting `quarkus.package.jar.enabled` to `false`.	string	`jar`
`quarkus.package.jar.manifest.add-implementation-entries`	Determines whether the implementation information is included in the runner JAR file’s `MANIFEST.MF`.	boolean	`true`
`quarkus.package.jar.user-configured-ignored-entries`	Specifies a list of files that must not be copied to the output artifact.	string (list)	(none)
`quarkus.package.runner-suffix`	Specifies the suffix applied to the runner JAR file.	string	`-runner`
`quarkus.package.output-directory`	Specifies the output folder for the application build. The path is resolved relative to the build system target directory.	string	(none)
`quarkus.package.output-name`	Specifies the name of the final build artifact.	string	(none)

Example: Configure the application output name

You can customize the name of your build output by configuring the quarkus.package.output-name property to align with your project conventions or deployment requirements.

Procedure

Open the src/main/resources/application.properties file.

Add the following property:

quarkus.package.output-name=my-quarkus-custom-app-name

Build the application:
```
./mvnw clean package
```
Verify that the resulting application JAR file is named:
```
my-quarkus-custom-app-name.jar
```

Test your IBM Enterprise Build of Quarkus application in JVM mode with a custom profile

By default, IBM Enterprise Build of Quarkus runs tests under the test configuration profile in Java virtual machine (JVM) mode, so properties prefixed with %test in src/main/resources/application.properties take precedence over their unprefixed counterparts. To run tests under a different profile, for example to exercise the application against different database instances, override the active profile by setting the quarkus.test.profile system property when you run Maven.

For an example of how %test properties take precedence, given the following configuration the value returned for the message property is Test Value under test and Hello under any other profile:

message=Hello
%test.message=Test Value

For information about standard testing with the "Starting With Quarkus" example, see Testing your IBM Enterprise Build of Quarkus application in the Test your application guide.

Prerequisites

A Quarkus project created with Apache Maven.

Procedure

To run tests under a custom profile, enter the following command:
```
mvn test -Dquarkus.test.profile=<profile_name>
```
Note: You cannot use a custom test configuration profile in native mode. Native tests always run under the prod profile.

Log the IBM Enterprise Build of Quarkus application build classpath tree

The Quarkus build process adds deployment dependencies of the extensions that you use in the application to the original application classpath. You can view the dependencies and versions included in the build classpath. The quarkus-maven-plugin Maven plugin includes the dependency-tree goal, which displays the build dependency tree for the application.

Prerequisites

You have created a Quarkus Maven application.

Procedure

To list the build dependency tree of your application, enter the following command:

./mvnw quarkus:dependency-tree

Example output. The exact output you see will differ from this example.

[INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:3.33.1.redhat-00002 (compile)
[INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:3.33.1.redhat-00002 (compile)
[INFO]    │  ├─ io.quarkus:quarkus-resteasy-common-deployment:jar:3.33.1.redhat-00002 (compile)
[INFO]    │  │  ├─ io.quarkus:quarkus-resteasy-common:jar:3.33.1.redhat-00002 (compile)
[INFO]    │  │  │  ├─ org.jboss.resteasy:resteasy-core:jar:6.2.4.Final-redhat-00003 (compile)
[INFO]    │  │  │  │  ├─ jakarta.xml.bind:jakarta.xml.bind-api:jar:4.0.0.redhat-00008 (compile)
[INFO]    │  │  │  │  ├─ org.jboss.resteasy:resteasy-core-spi:jar:6.2.4.Final-redhat-00003 (compile)
[INFO]    │  │  │  │  ├─ org.reactivestreams:reactive-streams:jar:1.0.4.redhat-00003 (compile)
[INFO]    │  │  │  │  └─ com.ibm.async:asyncutil:jar:0.1.0.redhat-00010 (compile)
...

Note: The mvn dependency:tree command displays only the runtime dependencies of your application.

Native executables and methods for building them

A native binary is an executable that is created to run on a specific operating system and CPU architecture.

The following list outlines some examples of a native executable:

An ELF binary for Linux AMD 64 bits
An EXE binary for Windows AMD 64 bits
An ELF binary for ARM 64 bits

Note: Only the ELF binary for Linux x86-64 or AArch64 bits is supported in IBM Enterprise Build of Quarkus.

One advantage of building a native executable is that your application and dependencies, including the Java Virtual Machine (JVM), are packaged into a single file. The native executable for your application contains the following items:

The compiled application code
The required Java libraries
A reduced version of the virtual machine (VM) for improved application startup times and minimal disk and memory footprint, which is also tailored for the application code and its dependencies

To produce a native executable from your Quarkus application, you can select either an in-container build or a local-host build. The following table explains the different building options that you can use:

Table 2. Building options for producing a native executable
Building option	Requires	Uses	Results in	Benefits
In-container build - Supported	A container runtime, for example, Podman or Docker	The default `registry.access.redhat.com/quarkus/mandrel-25-rhel9:25.0` builder image	A Linux 64-bit executable using the CPU architecture of the host	GraalVM does not need to be set up locally, which makes your CI pipelines run more efficiently
Local-host build - Only supported upstream	A local installation of GraalVM or Mandrel	Its local installation as a default for the `quarkus.native.builder-image` property	An executable that has the same operating system and CPU architecture as the machine on which the build is executed	An alternative for developers who are not allowed or do not want to use tools such as Docker or Podman. Overall, it is faster than the in-container build approach.

Important:

To build native Linux executables, IBM Enterprise Build of Quarkus supports using the IBM Enterprise Build of Quarkus Native builder image (quarkus/mandrel-25-rhel9), which is based on GraalVM Mandrel.

While other images are available in the Quarkus community, the product does not support them. Use only supported images for production builds that require IBM support.
Applications whose source is written based on 17, with no Java 18 - 25 features used, can still compile a native executable of that application by using the Java 25-based Mandrel 25.0 base image.
IBM Enterprise Build of Quarkus does not support building native executables by using Oracle GraalVM Community Edition (CE), Mandrel community edition, or any other GraalVM distributions. For more information, see Compile applications to native executables.

Additional resources

CI pipelines

Produce a native executable by using an in-container build

To create a native executable and run the native image tests, use the native profile that is provided by IBM Enterprise Build of Quarkus for an in-container build.

Prerequisites

Podman or Docker is installed.
The container has access to at least 8GB of memory.
Optional: You have installed the Quarkus CLI, which is one of the methods you can use to build a native executable. For more information, see Installing the Quarkus CLI.

Procedure

Open the Getting Started project pom.xml file, and verify that the project includes the native profile:

<profiles>
  <profile>
    <id>native</id>
    <activation>
      <property>
        <name>native</name>
      </property>
    </activation>
    <properties>
      <skipITs>false</skipITs>
      <quarkus.native.enabled>true</quarkus.native.enabled>
    </properties>
  </profile>
</profiles>

Build a native executable by using one of the following methods:

Using Maven:

For Docker:

./mvnw package -Dnative -Dquarkus.native.container-build=true

For Podman:

./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

Using the Quarkus CLI:

For Docker:

quarkus build --native -Dquarkus.native.container-build=true

For Podman:

quarkus build --native -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

These commands create a \*-runner binary in the target directory, where the following applies:

The \*-runner file is the built native binary that Quarkus produces.

The target directory is a directory that Maven creates when you build a Maven application.

Important: Compiling a Quarkus application to a native executable consumes a large amount of memory during analysis and optimization. You can limit the amount of memory used during native compilation by setting the quarkus.native.native-image-xmx configuration property. Setting low memory limits might increase the build time.

To run the native executable, enter the following command:
```
./target/*-runner
```

Additional resources

Native executable configuration properties

Produce a native executable by using a local-host build

If you are not using Docker or Podman, use the Quarkus local-host build option to create and run a native executable.

Using the local-host build approach is faster than using containers and is suitable for Linux-based machines.

Important: IBM Enterprise Build of Quarkus does not support the following procedure in production. Use this method only for testing or as a backup when Docker or Podman is unavailable.

Prerequisites

A local installation of Mandrel or GraalVm, correctly configured according to the Quarkus Building a native executable guide.
- Additionally, for a GraalVM installation, native-image must also be installed.
Optional: You have installed the Quarkus CLI, which is one of the methods you can use to build a native executable. For more information, see Installing the Quarkus CLI.

Procedure

For GraalVM or Mandrel, build a native executable by using one of the following methods:
- Using Maven:
  ./mvnw package -Dnative
- Using the Quarkus CLI:
  quarkus build --native
  These commands create a *-runner binary in the target directory, where the following applies: * The *-runner file is the built native binary that Quarkus produces. * The target directory is a directory that Maven creates when you build a Maven application.
  
  +
  
  Note: When you build the native executable, the prod profile is enabled unless modified in the quarkus.profile property.
Run the native executable:
```
./target/*-runner
```

Additional resources

Producing a native executable in the Quarkus community guide

Create a container manually

You can manually create a container image with your application for Linux AMD64. When you produce a native image by using the Quarkus Native container, the native image creates an executable that targets Linux AMD64. If your host operating system is different from Linux AMD64, you cannot run the binary directly and need to create a container manually.

Your Quarkus Getting Started project includes a Dockerfile.native in the src/main/docker directory with the following content:

FROM registry.access.redhat.com/ubi9-minimal:9.7
WORKDIR /work/
RUN chown 1001 /work \
    && chmod "g+rwX" /work \
    && chown 1001:root /work
COPY --chown=1001:root target/*-runner /work/application

EXPOSE 8080
USER 1001

ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]

The Dockerfile references a Red Hat Universal Base Image (UBI). The following UBI variants are suitable for use with Dockerfiles:

Red Hat Universal Base Image 9 (UBI9). This base image is designed and engineered as the base layer for containerized applications, middleware, and utilities.
```
registry.access.redhat.com/ubi9/ubi:9.7
```
Red Hat Universal Base Image 9 Minimal (UBI9-minimal). A stripped-down UBI9 image that uses microdnf as a package manager.
```
registry.access.redhat.com/ubi9-minimal:9.7
```

All IBM Base images are available on the Container images catalog site.

Procedure

Build a native Linux executable by using one of the following methods:

Docker:

./mvnw package -Dnative -Dquarkus.native.container-build=true

Podman:

./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

Build the container image by using one of the following methods:

Docker:

docker build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .

Podman

podman build -f src/main/docker/Dockerfile.native -t quarkus-quickstart/getting-started .

Run the container by using one of the following methods:

Docker:

docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started .

Podman:

podman run -i --rm -p 8080:8080 quarkus-quickstart/getting-started .

Test the native executable

Test the application in native mode to test the functionality of the native executable. Use the @QuarkusIntegrationTest annotation to build the native executable and run tests against the HTTP endpoints.

Important: The following example shows how to test a native executable with a local installation of GraalVM or Mandrel. Before you begin, consider the following points:

IBM Enterprise Build of Quarkus does not support this scenario, as outlined in Producing a native executable by using a local-host build.
The native executable you are testing with here must match the operating system and architecture of the host. Therefore, this procedure does not work if the native binary is built in a container on macOS.

Procedure

Open the pom.xml file and verify that the build section has the following elements:

<plugin>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>${surefire-plugin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <argLine>@{argLine}</argLine>
        <systemPropertyVariables>
            <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
            <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
            <maven.home>${maven.home}</maven.home>
        </systemPropertyVariables>
    </configuration>
</plugin>

The Maven Failsafe plugin (maven-failsafe-plugin) runs the integration test and indicates the location of the native executable that is generated.

Open the src/test/java/org/acme/GreetingResourceIT.java file and verify that it includes the following content:
```
package org.acme;

import io.quarkus.test.junit.QuarkusIntegrationTest;

@QuarkusIntegrationTest
public class GreetingResourceIT extends GreetingResourceTest {

    // Execute the same tests but in native mode.
}
```
where:
- @QuarkusIntegrationTest
  - Use another test runner that starts the application from the native file before the tests. The executable is retrieved by using the native.image.path system property configured in the Maven Failsafe plugin.
- public class GreetingResourceIT extends GreetingResourceTest {
  - This example extends the GreetingResourceTest, but you can also create a new test.

Run the test:

./mvnw verify -Dnative

The following example shows the output of this command:

./mvnw verify -Dnative
....

GraalVM Native Image: Generating 'getting-started-1.0.0-SNAPSHOT-runner' (executable)...
========================================================================================================================
[1/8] Initializing...                                                                                    (6.6s @ 0.22GB)
Java version: 25.0.2+10-LTS, vendor version: Mandrel-25.0.2.0-4b8
Graal compiler: optimization level: 2, target machine: x86-64-v3
C compiler: gcc (redhat, x86_64, 11.5.0)
Garbage collector: Serial GC (max heap size: 80% of RAM)
 2 user-specific feature(s)
 - io.quarkus.runner.Feature: Auto-generated class by Quarkus from the existing extensions
 - io.quarkus.runtime.graal.DisableLoggingFeature: Disables INFO logging during the analysis phase
[2/8] Performing analysis...  [******]                                                                  (40.0s @ 2.05GB)
  10,318 (86.40%) of 11,942 types reachable
  15,064 (57.36%) of 26,260 fields reachable
  52,128 (55.75%) of 93,501 methods reachable
   3,298 types,   109 fields, and 2,698 methods registered for reflection
      63 types,    68 fields, and    55 methods registered for JNI access
       4 native libraries: dl, pthread, rt, z
[3/8] Building universe...                                                                               (5.9s @ 1.31GB)
[4/8] Parsing methods...      [**]                                                                       (3.7s @ 2.08GB)
[5/8] Inlining methods...     [***]                                                                      (2.0s @ 1.92GB)
[6/8] Compiling methods...    [******]                                                                  (34.4s @ 3.25GB)
[7/8] Layouting methods...    [**]                                                                       (4.1s @ 1.78GB)
[8/8] Creating image...       [**]                                                                       (4.5s @ 2.31GB)
  20.93MB (48.43%) for code area:    33,233 compilation units
  21.95MB (50.80%) for image heap:  285,664 objects and 8 resources
 337.06kB ( 0.76%) for other data
  43.20MB in total

....


[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M7:integration-test (default) @ getting-started ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.acme.GreetingResourceIT
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2024-09-27 14:04:52,681 INFO  [io.quarkus] (main) getting-started 1.0.0-SNAPSHOT native (powered by Quarkus 3.33.1.redhat-00002) started in 0.038s. Listening on: http://0.0.0.0:8081
2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Profile prod activated.
2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.696 s - in org.acme.GreetingResourceIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M7:verify (default) @ getting-started ---

Note: Quarkus waits 60 seconds for the native image to start before automatically failing the native tests. You can change this duration by configuring the quarkus.test.wait-time system property.

You can extend the wait time by using the following command, where <duration> is the wait time in seconds:

./mvnw verify -Dnative -Dquarkus.test.wait-time=<duration>

Note:

By default, native tests run by using the prod profile unless modified in the quarkus.test.integration-test-profile property.

Use IBM Enterprise Build of Quarkus development mode

Development (dev) mode enables hot deployment with background compilation, which means that when you modify your Java or resource files and then refresh your browser, the changes take effect immediately. This also applies to resource files, such as the configuration property file. You can use either Maven or the Quarkus command-line interface (CLI) to start Quarkus in development mode.

Prerequisites

You have created a Quarkus Maven application.
Optional: You have installed the Quarkus CLI, which is one of the methods you can use to start Quarkus in development mode. For more information, see Installing the Quarkus CLI.

Procedure

Switch to the directory that contains your Quarkus application pom.xml file.
To compile and start your Quarkus application in development mode, use one of the following methods:
- Using Maven:
  ./mvnw quarkus:dev
- Using the Quarkus CLI:
  quarkus dev
Make changes to your application and save the files.
Refresh the browser to trigger a scan of the workspace.

If any changes are detected, the Java files are recompiled and the application is redeployed. The redeployed application then services your request. If there are any issues with compilation or deployment, an error page appears.

In development mode, the debugger is activated and listens on port 5005.
Optional: To wait for the debugger to attach before running the application, include -Dsuspend:
```
./mvnw quarkus:dev -Dsuspend
```
Optional: To prevent the debugger from running, include -Ddebug=false:
```
./mvnw quarkus:dev -Ddebug=false
```

Debugging Quarkus applications in development mode

When IBM Enterprise Build of Quarkus runs in development mode, the JVM is configured for debugging by default. The debugger listens on port 5005, binds to localhost for security, and does not suspend startup, so you can attach a debugger from your IDE without changing any configuration.

Attaching a debugger to a running application

To debug a Quarkus application in development mode, start the application with ./mvnw quarkus:dev, then attach your IDE’s remote JVM debug configuration to localhost:5005. With the debugger attached, set breakpoints in your code and trigger the relevant code path. The debugger pauses execution at each breakpoint.

Because the application is fully started by the time you attach, the debugger cannot pause execution in code that runs during application startup, such as CDI bean initialization or startup-event observers. To debug startup code, suspend the JVM until the debugger attaches.

Customizing dev-mode debugging

The defaults suit most cases of attaching a local IDE to a local dev-mode application. You typically need to customize debugging only in the following situations:

You want to debug code that runs during application startup, and need the JVM to wait for a debugger before running.
The application and the debugger run on different machines, containers, or virtual machines.
Port 5005 is already in use, or you want to disable debugging entirely.

You control these behaviors by passing parameters to the Quarkus Maven plugin or Quarkus CLI on the command line. These parameters are not Quarkus configuration properties: setting them in application.properties has no effect. For valid values and defaults, see Dev-mode debugging parameters in Additional resources.

suspend

Controls whether the JVM waits for a debugger to attach before running your application. Use suspend=y when you need to debug code that runs early in the application lifecycle. When the JVM is suspended, it prints Listening for transport dt_socket at address: <port> in the startup log.

For example:

Maven:
```
./mvnw quarkus:dev -Dsuspend
```
Quarkus CLI:
```
quarkus dev --suspend
```

debugHost

Controls which network interface the JDWP debug agent binds to. Change debugHost when the debugger runs on a different machine, container, or VM than the application. Any host that can reach the port can attach a debugger and execute arbitrary code, so avoid 0.0.0.0 on shared Wi-Fi, in public cloud environments without firewall rules, or on any network where untrusted hosts can reach your machine.

For example, to bind the debugger to a specific network interface, replace <host-ip-address> with the IP address of the interface:

Maven:

./mvnw quarkus:dev -DdebugHost=<host-ip-address>

Quarkus CLI:

quarkus dev --debug-host=<host-ip-address>

debug

Controls whether the debugger is enabled and on which port. Change debug when port 5005 is already in use, or when you want to start the application without the debug agent.

For advanced JDWP connect-mode debugging, where the JVM connects out to a listening debugger, see the Debugging section in the upstream Quarkus documentation, listed in Additional resources.

For example, to listen on a custom port:

Maven:
```
./mvnw quarkus:dev -Ddebug=6006
```
Quarkus CLI:
```
quarkus dev --debug-port=6006
```

Additional resources

Dev-mode debugging parameters

The following parameters control the JVM debug agent when IBM Enterprise Build of Quarkus runs in development mode. You pass these on the command line as Quarkus Maven plugin parameters (for example, -Dsuspend) or Quarkus CLI options (for example, --suspend). These are not Quarkus configuration properties and have no effect when set in application.properties.

Table 3. Dev-mode debugging parameters
Parameter	Valid values	Default
`debug`	A port number to listen on; `true` to listen on the default port `5005`; `false` to disable debugging.	`true`
`debugHost`	An IP address to bind the debug agent to; `0.0.0.0` to bind to all interfaces.	`localhost`
`suspend`	`y` or `true` to suspend the JVM at startup until a debugger attaches; `n` or `false` to start without suspending.	`n`

Additional resources

Debugging in the upstream Quarkus documentation

Additional resources

Revised on 2026-06-01 23:31:49 UTC