Quarkus Guides

https://quarkus.io/guides
Admin
Quarkus is a Kubernetes Native Java stack tailored for GraalVM and OpenJDK HotSpot, crafted from...
Tokens:2,598,108
Snippets:20,784
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start gdb with source cache example

Source: https://quarkus.io/guides/building-native-image

Example of starting gdb with the source cache in the target directory and the native executable for a getting-started project.

```bash
gdb -ex 'directory ./target' ./target/getting-started-1.0.0-SNAPSHOT-runner
```

--------------------------------

### Run SAM local start-api

Source: https://quarkus.io/guides/aws-lambda-http

Starts a local simulated Lambda environment using Docker. Requires Docker to be installed and the Maven project built. After startup, invoke the example lambda at http://127.0.0.1:3000/hello.

```bash
sam local start-api --template target/sam.jvm.yaml
```

--------------------------------

### Clone the Quarkus quickstarts repository

Source: https://quarkus.io/guides/getting-started-dev-services

Clone the Quarkus quickstarts repository to access the completed example for this tutorial. The solution is located in the getting-started-dev-services directory.

```bash
git clone https://github.com/quarkusio/quarkus-quickstarts.git
```

--------------------------------

### Startup log with installed features

Source: https://quarkus.io/guides/writing-extensions

Example startup log lines showing the installed features list, including the feature name 'test-extension'. The annotation (1) refers to the list of features installed in the runtime image.

```text
2019-03-22 14:02:37,884 INFO  [io.quarkus] (main) Quarkus 999-SNAPSHOT started in 0.061s.
2019-03-22 14:02:37,884 INFO  [io.quarkus] (main) Installed features: [cdi, test-extension] __**(1)**
```

--------------------------------

### List installable plugins with filter

Source: https://quarkus.io/guides/cli-tooling

Lists installable plugins filtered by name pattern using -s flag. The example shows filtering for names starting with 'k'.

```shell
quarkus plugin list --installable -s "k*"
    Name    	 Type       	 Scope 	 Location                          	 Description
    kill    	 jbang     	 user  	 quarkus-kill@quarkusio

Use the 'plugin add' subcommand and pass the location of any plugin listed above, or any remote location in the form of URL / GACTV pointing to a remote plugin.
```

--------------------------------

### Start gdb with source cache

Source: https://quarkus.io/guides/building-native-image

Start gdb with the source cache directory and the native executable path. The example uses placeholders for the project name and version.

```bash
gdb -ex 'directory path/to/target' path/to/target/{project.name}-{project.version}-runner
```

--------------------------------

### Add configuration reference tip

Source: https://quarkus.io/guides/writing-extensions

Place this tip just below an `application.properties` example in the guide to point readers to the Configuration Reference section.

```asciidoc
[TIP]
For more information about the extension configuration please refer to the <<configuration-reference,Configuration Reference>>.
```

--------------------------------

### codestart.yml example

Source: https://quarkus.io/guides/extension-codestart

Example codestart.yml configuration for an extension codestart. Defines the codestart name, reference, type, tags, and metadata including title, description, related guide, and optional path.

```yaml
# codestart unique name
name: resteasy-example
# codestart reference, use the extension id
ref: resteasy
# use 'code' (other types are for base codestarts)
type: code
# use 'extension-codestart'
tags: extension-codestart
# public metadata for this example (accessible as data in the templates e.g. {title})
metadata:
  title: RESTEasy Jakarta REST example
  description: Rest is easy peasy with this Hello World RESTEasy resource.
  related-guide-section: https://quarkus.io/guides/getting-started#the-jax-rs-resources
  # (optional) use this in web extensions with a specific path (and also add the index page)
  path: /some-path
```

--------------------------------

### Complete worked example of the tutorial document

Source: https://quarkus.io/guides/doc-create-tutorial

The full AsciiDoc source of the tutorial, including metadata, prerequisites, and all sections. It is the reference for the complete tutorial.

```asciidoc
////
This document is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
[id="acme-serve-http-requests-tutorial"]
= Serve Http requests using the Acme extension
include::_attributes.adoc[]
:diataxis-type: tutorial
:extension-status: experimental

Create an application that uses unique annotations from the experimental acme extension to define two endpoints:
a simple HTTP endpoint and an endpoint that emits server-sent events (SSE).
We will also use Quarkus dev mode for iterative development and testing.

include::{includes}/extension-status.adoc[]

== Prerequisites

:prerequisites-time: 30 minutes
:prerequisites-docker:
:prerequisites-no-graalvm:

include::{includes}/prerequisites.adoc[]

The `curl` command line utility is also used to manually test the endpoint.

:sectnums:
:sectnumlevels: 3
== Create a new project

Create a new project with the following command:

:create-app-artifact-id: acme-quickstart
:create-app-extensions: acme
include::{includes}/devtools/create-app.adoc[]

== Hello, World! as an Acme Http service

Let's create a Http endpoint using the `@Anvil` annotation.

Create a new source file, `src/main/java/org/acme/MyAcmeApplication.java`,
and define the `MyAcmeApplication` bean as follows:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplication.java[tags=*;!goodbye]
----

<1> Specify the CDI lifecycle of this bean.
An `@ApplicationScoped` bean has a single bean instance that is used for the application.
<2> The `@Anvil` annotation always implies a simple Http GET request with the uri derived from the method name, `/hello` in this case.
The `optional` value indicates that the `name` parameter is not required.

== Dev Mode: Hello, World!

Let's run our application using Quarkus' iterative development mode:

include::{includes}/devtools/dev.adoc[]

Once the console output from dev mode indicates that things are ready, use `curl` to invoke the `hello` endpoint:

[source,shell]
----
$ curl -w "\n" http://localhost:8080/hello
Hello, World!
----

Pass the name as a parameter:

[source,bash,subs=attributes+]
----
$ curl localhost:8080/hello -d '{"name": "bananas"}'
Hello, bananas!
----

You can leave dev mode running throughout the rest of the tutorial for continuous feedback as you make changes to code.
Use `CTRL-C` to exit dev mode.

== Testing: Hello, World!

Let's create a test to work with our `@Anvil` endpoint.

Create a new source file, `src/test/java/org/acme/MyAcmeApplicationTest.java`, and define `MyAcmeApplicationTest` as follows:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tags=*;!goodbye]
----

After saving, the dev console should detect the presence of tests, but it isn't running by default.
The bottom of the console screen will display a message indicating that running tests have been paused.

Press `r` to resume testing.
You should see the status change as they are running, and it should finish with a message indicating that 1 test was run and that it was successful.

== Goodbye, Sweet Planet! Server sent events with Acme

Let's add an endpoint that supports Server Sent Events using the `@Toaster` annotation:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplication.java[tag=goodbye]
----
<1> The `@Toaster` annotation indicates that this method emits Server-Sent Events.
<2> A `Multi` is an asynchronous publisher of multiple events provided by Mutiny, the event-driven reactive streams library used by Quarkus.

== Testing: Goodbye, Sweet Planet!

Let's create a test to work with our `@Toaster` endpoint.

Add the following method to `src/test/java/org/acme/MyAcmeApplicationTest.java`:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tag=goodbye]
----

After saving, the dev console should detect the presence of the additional test, and run both.
You should see a message that 2 tests were run, and both were successful.

:sectnums!:
== Summary

Congratulations!
You have created a project that uses the acme extension to create fanciful endpoints using the `@Anvil` and `@Toaster` annotations.
```

--------------------------------

### Example JSON response from GET /fruits

Source: https://quarkus.io/guides/getting-started-reactive

Example JSON array returned when invoking the GET /fruits endpoint. Shows the expected output format.

```json
[{"id":2,"name":"Apple"},{"id":3,"name":"Banana"},{"id":1,"name":"Cherry"},{"id":4,"name":"peach"}]
```

--------------------------------

### Start a build

Source: https://quarkus.io/guides/deploying-to-openshift-s2i-howto

Deploy an updated version of the project after pushing changes to the Git repository.

```bash
oc start-build <project_name>
```

--------------------------------

### Startup task execution times output

Source: https://quarkus.io/guides/writing-extensions

Example output when launching Quarkus with -Dquarkus.debug.print-startup-times=true, showing the time each startup task takes.

```text
Build step LoggingResourceProcessor.setupLoggingRuntimeInit completed in: 42ms
Build step ConfigGenerationBuildStep.checkForBuildTimeConfigChange completed in: 4ms
Build step SyntheticBeansProcessor.initRuntime completed in: 0ms
Build step ConfigBuildStep.validateConfigProperties completed in: 1ms
Build step ResteasyStandaloneBuildStep.boot completed in: 95ms
Build step VertxHttpProcessor.initializeRouter completed in: 1ms
Build step VertxHttpProcessor.finalizeRouter completed in: 4ms
Build step LifecycleEventsBuildStep.startupEvent completed in: 1ms
Build step VertxHttpProcessor.openSocket completed in: 93ms
Build step ShutdownListenerBuildStep.setupShutdown completed in: 1ms
```

--------------------------------

### Example: docker top to get RSS

Source: https://quarkus.io/guides/performance-measure

Example command that uses docker top with a filter to get the RSS of a Quarkus application container, showing the output with PID, RSS, and command.

```bash
$ docker top $(docker ps -q --filter ancestor=quarkus/myapp) -o pid,rss,args

PID                 RSS                 COMMAND
2531                27m                 ./application -Dquarkus.http.host=0.0.0.0
```

--------------------------------

### Qute tag parsing examples

Source: https://quarkus.io/guides/qute-reference

Tag examples showing which tags are parsed and which are ignored. `{_foo.bar}` is parsed (expression starting with underscore), `{! comment !}` is parsed (comment), while `{  foo}`, `{{foo}}`, and `{"foo":true}` are ignored because they start with whitespace, `{`, or `"` respectively.

```html
<html>
   <body>
   {_foo.bar}   **(1)**
   {! comment !}**(2)**
   {  foo}      **(3)**
   {{foo}}      **(4)**
   {"foo":true} **(5)**
   </body>
</html>
```

--------------------------------

### Example response from /q/info endpoint

Source: https://quarkus.io/guides/info

Example JSON response from the /q/info endpoint. It contains up to four sections: os, java, build, and git. Each section can be individually enabled or disabled via configuration. The git section is only present if the project is in a Git repository; otherwise it is omitted.

```json
{
  "os": {
    "name": "Mac OS X",
    "version": "15.5",
    "arch": "aarch64"
  },
  "java": {
    "version": "21.0.7",
    "vendor": "Eclipse Adoptium",
    "vendorVersion": "Temurin-21.0.7+6"
  },
  "build": {
    "group": "org.acme",
    "artifact": "getting-started",
    "version": "1.0.0-SNAPSHOT",
    "time": "2026-05-21T10:30:00Z",
    "quarkusVersion": "{quarkus-version}"
  },
  "git": {
    "branch": "main",
    "commit": {
      "id": "a1b2c3d",
      "time": "2026-05-20T14:22:00Z"
    }
  }
}
```

--------------------------------

### Run greeting-app in dev mode and verify extension

Source: https://quarkus.io/guides/building-my-first-extension

Starts the application in dev mode. The output shows the Installed Features list includes greeting-extension, confirming the extension is active.

```bash
$ mvn quarkus:dev
[INFO] Scanning for projects...
[INFO]
[INFO] -----------------------< org.acme:greeting-app >------------------------
[INFO] Building greeting-app 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-compiler-plugin:3.15.0:compile (default-compile) @ greeting-app ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- quarkus-maven-plugin:3.40.1:dev (default-cli) @ greeting-app ---
Listening for transport dt_socket at address: 5005
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2022-11-20 04:25:36,885 INFO  [io.quarkus] (Quarkus Main Thread) greeting-app 1.0.0-SNAPSHOT on JVM (powered by Quarkus 3.40.1) started in 4.591s. Listening on: http://localhost:8080
2022-11-20 04:25:36,911 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2022-11-20 04:25:36,913 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, greeting-extension, resteasy-reactive, smallrye-context-propagation, vertx]
```

--------------------------------

### Endpoint class for interceptor example

Source: https://quarkus.io/guides/rest

A Jakarta REST endpoint with GET and PUT methods that serves as the target for the reader and writer interceptors shown in the next example.

```java
package org.acme.rest;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;

@Path("cheese")
public class Endpoint {

    @GET
    public String sayCheese() {
        return "Cheeeeeese";
    }

    @PUT
    public void addCheese(String cheese) {
        System.err.println("Received a new cheese: " + cheese);
    }
}

```

--------------------------------

### Console output when Keycloak Dev Services starts

Source: https://quarkus.io/guides/security-openid-connect-dev-services

Example console output when Dev Services for Keycloak starts. It shows the container waiting for a URL and the startup message.

```text
KeyCloak Dev Services Starting:
2021-11-02 17:14:24,864 INFO  [org.tes.con.wai.str.HttpWaitStrategy] (build-10) /unruffled_agnesi: Waiting for 60 seconds for URL: http://localhost:32781 (where port 32781 maps to container port 8080)
2021-11-02 17:14:44,170 INFO  [io.qua.oid.dep.dev.key.KeycloakDevServicesProcessor] (build-10) Dev Services for Keycloak started.
```

--------------------------------

### Example deploy command for Java 21

Source: https://quarkus.io/guides/deploying-to-openshift-s2i-howto

Example command for Java 21. Use the HTTPS URL if SSH keys are not configured.

```bash
oc new-app registry.access.redhat.com/ubi9/openjdk-21~https://github.com/johndoe/code-with-quarkus.git --name=code-with-quarkus
```

--------------------------------

### Create lorem.txt file with sample content

Source: https://quarkus.io/guides/vertx

Create a file named lorem.txt in the src/main/resources directory with the provided Lorem ipsum text. This file is used by the Vert.x File System API example.

```text
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
```

--------------------------------

### Install a specific Quarkus CLI version using JBang

Source: https://quarkus.io/guides/cli-tooling

Install a specific version of the Quarkus CLI by targeting the runner JAR directly. The example creates an alias 'qs3.8.6' for version 3.8.6.

```bash
# Create an alias in order to use a specific version
jbang app install --name qs3.8.6 https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/3.8.6/quarkus-cli-3.8.6-runner.jar
```

--------------------------------

### Install greeting-extension locally with Maven

Source: https://quarkus.io/guides/building-my-first-extension

Run from the greeting-extension directory to install the extension into the local Maven repository, making it available for use in applications.

```bash
cd ./greeting-extension
mvn clean install
```

--------------------------------

### Mock REST client with QuarkusMock

Source: https://quarkus.io/guides/rest-client

Use QuarkusMock to programmatically install a mock for a REST client type when Mockito is not sufficient. The mock is created manually and installed with QuarkusMock.installMockForType, passing RestClient.LITERAL as the last argument. The example shows a @BeforeEach method that installs the mock before each test.

```java
package io.quarkus.it.rest.client.main;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import io.quarkus.test.junit.QuarkusMock;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
public class QuarkusMockTest {

    @BeforeEach
    public void setUp() {
        Client customMock = new Client() { __**(1)**
            @Override
            public String get() {
                return "MockAnswer";
            }
        };
        QuarkusMock.installMockForType(customMock, Client.class, RestClient.LITERAL); __**(2)**
    }
    @Test
    void doTest() {
        // ...
    }
}

```

--------------------------------

### Find method by name

Source: https://quarkus.io/guides/native-reference

Example query to start exploring the graph by looking for a method with a given name.

```cypher
match (m:Method) where m.name = "hello" return *
```

--------------------------------

### ConfigYamlCodestartTest example

Source: https://quarkus.io/guides/extension-codestart

Example test class for a Quarkus codestart. Uses QuarkusCodestartTest to verify generated sources and snapshots, and optionally builds all projects when the build-projects system property is enabled.

```java
public class ConfigYamlCodestartTest {

    @RegisterExtension
    public static QuarkusCodestartTest codestartTest = QuarkusCodestartTest.builder()
            .codestarts("config-yaml")
            .languages(JAVA, KOTLIN)
            .build();

    @Test
    void testContent() throws Throwable {
        codestartTest.checkGeneratedSource("org.acme.GreetingConfig");
        codestartTest.assertThatGeneratedFileMatchSnapshot(JAVA, "src/main/resources/application.yml");
    }

    @Test
    @EnabledIfSystemProperty(named = "build-projects", matches = "true")
    void buildAllProjectsForLocalUse() throws Throwable {
        codestartTest.buildAllProjects();
    }

}
```

--------------------------------

### Build AMQP quickstart applications in JVM mode

Source: https://quarkus.io/guides/amqp

Build both applications in JVM mode. After packaging, run `docker compose up --build` and access the UI at http://localhost:8080/quotes.html.

```shell
> mvn -f amqp-quickstart-producer clean package
> mvn -f amqp-quickstart-processor clean package
```

--------------------------------

### Install locally built Quarkus CLI snapshot using JBang

Source: https://quarkus.io/guides/cli-tooling

Use a locally built snapshot of the Quarkus CLI by installing the runner JAR from the local Maven repository. The example uses the alias 'qss'.

```bash
# Use the latest (or locally built) snapshot (with qss as an alias)
jbang app install --force --name qss ~/.m2/repository/io/quarkus/quarkus-cli/999-SNAPSHOT/quarkus-cli-999-SNAPSHOT-runner.jar
```

--------------------------------

### Swagger UI log output

Source: https://quarkus.io/guides/openapi-swaggerui

Example log output showing the Swagger UI path when the application starts.

```log
00:00:00,000 INFO  [io.qua.swa.run.SwaggerUiServletExtension] Swagger UI available at /q/swagger-ui
```

--------------------------------

### Include configuration reference at end of guide

Source: https://quarkus.io/guides/writing-extensions

At the end of the guide, include the extensive configuration documentation. The `opts=optional` attribute is mandatory to avoid build failure when only part of the configuration documentation is generated.

```asciidoc
[[configuration-reference]]
== Configuration Reference

include::{generated-dir}/config/quarkus-your-extension.adoc[opts=optional, leveloffset=+1]
```

--------------------------------

### Display help for Quarkus create commands

Source: https://quarkus.io/guides/cli-tooling

Use `--help` to show options for creating projects with the `app` and `cli` subcommands.

```bash
quarkus create app --help
quarkus create cli --help
```

--------------------------------

### Example cache metrics output for Prometheus

Source: https://quarkus.io/guides/cache

Example Prometheus metrics output for a cache named 'foo' when using the quarkus-micrometer-registry-prometheus extension. Shows gauges and counters for size, puts, gets (hit/miss), evictions, and eviction weight.

```prometheus
# HELP cache_size The number of entries in this cache. This may be an approximation, depending on the type of cache.
# TYPE cache_size gauge
cache_size{cache="foo",} 8.0
# HELP cache_puts_total The number of entries added to the cache
# TYPE cache_puts_total counter
cache_puts_total{cache="foo",} 12.0
# HELP cache_gets_total The number of times cache lookup methods have returned a cached value.
# TYPE cache_gets_total counter
cache_gets_total{cache="foo",result="hit",} 53.0
cache_gets_total{cache="foo",result="miss",} 12.0
# HELP cache_evictions_total cache evictions
# TYPE cache_evictions_total counter
cache_evictions_total{cache="foo",} 4.0
# HELP cache_eviction_weight_total The sum of weights of evicted entries. This total does not include manual invalidations.
# TYPE cache_eviction_weight_total counter
cache_eviction_weight_total{cache="foo",} 540.0
```

--------------------------------

### Run the native executable with datasource configuration

Source: https://quarkus.io/guides/getting-started-reactive

Launch the native executable with the same datasource configuration properties.

```bash
./target/getting-started-with-reactive-runner \
  -Dquarkus.datasource.reactive.url=postgresql://localhost/fruits \
  -Dquarkus.datasource.username=quarkus \
  -Dquarkus.datasource.password=quarkus
```
Tokens:
Raw