Build your first application

Red Hat build of Quarkus 3.33

Red Hat Customer Content Services

Abstract

This guide describes how to create, run, and live-edit a simple Quarkus application with Apache Maven.

Chapter 1. Red Hat build of Quarkus overview

Red Hat build of Quarkus is a Kubernetes-native Java stack for building fast-starting, low-memory microservices, optimized for containers and Red Hat OpenShift Container Platform. It 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.

1.1. Why Quarkus?

Quarkus takes a container-first approach to building Java applications: applications start fast, use less memory than a traditional JVM stack, and are designed to fit into microservices and serverless architectures.

Quarkus optimizes the development process by providing unified configuration, automatic provisioning of unconfigured services (Dev Services), live coding, and continuous testing, giving you instant feedback on code changes without needing to restart.

For information about how Red Hat build of Quarkus differs from the Quarkus community version, see "Differences between the Quarkus community version and Red Hat build of Quarkus" in Additional resources.

1.2. JVM mode versus native mode

Quarkus applications run in one of two modes.

Choose the mode that best fits the primary constraint of your workload.

Java Virtual Machine (JVM) mode (default):

Offers the fastest path from code to a running application, with builds completing in approximately 30 seconds.
Provides the highest peak throughput.
Retains full JVM tooling including debuggers, profilers, and Java Flight Recorder (JFR).

Use JVM mode for long-running services and throughput-critical workloads.

Native mode (Mandrel):

Compiles the application to a standalone Linux binary that starts in 17–240 milliseconds and uses 3–5 times less memory than JVM mode.
Builds require 3–10 minutes and 4–8 GB of build-host RAM, and peak throughput is approximately half that of JVM mode.

Use native mode for serverless or scale-to-zero deployments, edge environments, or high-density container hosts where memory is the primary constraint.

1.3. Next steps

To get to a running application as quickly as possible, explore the "Build your first Quarkus application" guide, which uses JVM mode.

To deploy in native mode, see the "Compile applications to native executables" guide.

For a completed example, download the Quarkus Quickstarts archive or clone the Quarkus Quickstarts Git repository and go to the getting-started directory.

For links to these resources, see the following section.

Additional resources

Chapter 2. Build your first Quarkus application

Build, run, and live-edit a simple Quarkus REST application so you can see the developer feedback loop firsthand. You will generate a project with Apache Maven, run it in dev mode, hit a hello HTTP endpoint, and make a code change that takes effect without restarting.

To demonstrate dependency injection, the hello HTTP endpoint uses a greeting bean.

Note

For a completed example, download the Content from github.com is not included.Quarkus Quickstarts archive or clone the Content from github.com is not included.Quarkus Quickstarts Git repository and go to the getting-started directory.

Prerequisites

A Java 17, 21, or 25 compatible JVM installed. For example: Red Hat build of OpenJDK or an Adoptium-provided JDK, such as Eclipse Temurin.
- Download your preferred JVM:
  - Red Hat build of OpenJDK from the Red Hat Customer Portal This content is not included.Software Downloads page
  - An Eclipse Temurin distribution from the Content from adoptium.net is not included.Adoptium home 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 Content from maven.apache.org is not included.Apache Maven Project website.
The Red Hat-hosted Quarkus repository configured in the $HOME/.m2/settings.xml file. This ensures your project uses certified Red Hat build of Quarkus artifacts without needing repository details in the POM file of each project.

Procedure

Verify that Maven uses OpenJDK 17, 21, or 25, that the Maven version is 3.9.12, and that mvn is accessible from the PATH environment variable:
```
mvn --version
```
If the command does not show OpenJDK 17, 21, or 25, add the correct JDK to your PATH variable and run the command again.
Generate the project using the command for your shell:
- Linux or Apple macOS:
```
mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.33.1.redhat-00006:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -DplatformGroupId=com.redhat.quarkus.platform \
    -DplatformVersion=3.33.1.redhat-00006 \
    -DclassName="org.acme.quickstart.GreetingResource" \
    -Dpath="/hello"
cd getting-started
```
- Microsoft Windows command line:
```
mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.33.1.redhat-00006:create
-DprojectGroupId=org.acme -DprojectArtifactId=getting-started
-DplatformGroupId=com.redhat.quarkus.platform
-DplatformVersion=3.33.1.redhat-00006
-DclassName="org.acme.quickstart.GreetingResource"
-Dpath="/hello"
```
- Microsoft Windows PowerShell:
```
mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.33.1.redhat-00006:create
"-DprojectGroupId=org.acme"
"-DprojectArtifactId=getting-started"
"-DplatformVersion=3.33.1.redhat-00006"
"-DplatformGroupId=com.redhat.quarkus.platform"
"-DclassName=org.acme.quickstart.GreetingResource"
"-Dpath=/hello"
```
  The command creates a ./getting-started directory with a Maven project, a REST endpoint class at src/main/java/org/acme/quickstart/GreetingResource.java, unit tests for JVM and native modes, example Dockerfiles under src/main/docker/, and an application.properties configuration file.
  The generated pom.xml includes the Quarkus BOM (com.redhat.quarkus.platform:quarkus-bom), which manages all core Quarkus extension versions so you do not need to manage individual Quarkus dependency versions. The generated pom.xml also includes the quarkus-maven-plugin, which enables Maven to create Quarkus projects, package applications as JAR files, and run the application in dev mode. You invoke the plugin directly in the next step with the mvn quarkus:dev command. The quarkus-rest (formerly named quarkus-resteasy-reactive) dependency provides REST endpoint support.
  Note
  From Red Hat build of Quarkus version 3.15 onwards, quarkus-resteasy-reactive extensions are renamed to quarkus-rest. Applications that use quarkus-resteasy-reactive dependencies are invited to update their dependencies.

Start the application in dev mode.

mvn quarkus:dev

Or, if you prefer to use the Maven wrapper:

./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]

In a new terminal, call the endpoint:
```
curl -w "\n" http://localhost:8080/hello
```
The response is:
```
Hello from Quarkus REST
```
To confirm the dev-mode feedback loop, make a live code change. With mvn quarkus:dev still running in the first terminal, open src/main/java/org/acme/quickstart/GreetingResource.java in a text editor:
```
@Path("/hello")
public class GreetingResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello from Quarkus REST";
    }
}
```
Change the returned string to something else (for example, "Hello, world!") and save the file. Re-run the curl command.
Quarkus recompiles and reloads your change, and the updated response appears without restarting the application.

Verification

The first curl call returns Hello from Quarkus REST.
After you edit GreetingResource.java and save, the next curl call returns your new text, with no application restart needed.

Next steps

To learn about testing, packaging, native mode, dependency injection, or migrating from the Quarkus Community, see Next steps and related guides.

Chapter 3. Next steps and related guides

Continue your Quarkus journey with these guides, grouped by tasks you might want to explore or handle next.

3.1. Test and debug

To learn about JUnit-based unit tests, continuous testing mode, and the commands for controlling continuous testing in dev mode, see Test your application.

3.2. Package and run

You can package your application as a JAR file, compile it to a native executable, or containerize it for deployment.

Package and run your application

For more packaging and deployment options, including JVM-mode containerization, see the following documentation:

To compile your project into a native executable, configure, and test it, see Compile applications to native executables.
For JVM-mode packaging and containerization, see the Content from quarkus.io is not included.Quarkus Maven tooling guide.

3.3. Configure your application

Configure and extend your application using application.properties or application.yaml, and manage dependency injection with CDI.

Use application.properties to configure applications
Use application.yaml to configure applications
For dependency injection with CDI, see the Quarkus Content from quarkus.io is not included.Contexts and dependency injection guide.

3.4. Explore other ways to create Quarkus applications

You can also create Quarkus applications by using This content is not included.code.quarkus.redhat.com or the Quarkus command-line interface (CLI).

If you are migrating an existing community Quarkus Maven project to Red Hat build of Quarkus, you can reconfigure your Maven project to use Red Hat build of Quarkus BOM in place of the community BOM.

For more information, see Create Quarkus applications.

3.5. Configure your environment

To learn about configuration options for your environment, see Configure your environment.

Legal Notice

Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.

The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.

All other trademarks are the property of their respective owners.