This is a cache of https://developer.ibm.com/tutorials/quarkus-basics-04/. It is a snapshot of the page as it appeared on 2025-12-05T02:56:30.269+0000.
Configuring Quarkus applications - IBM Developer
IBM Developer

Tutorial

Configuring Quarkus applications

Unlock the full potential of Quarkus by understanding how to work with profiles, configuration files, and environment variables for optimal performance.

By

Markus Eisele

On this page

In this tutorial, you will learn how to manage application settings in Quarkus. Instead of hardcoding values, you will use configuration properties. You will also learn how Quarkus supports different profiles (dev, test, prod) so that your app can behave differently depending on where it runs.

Prerequisites

Before you begin, make sure that you have installed:

Step 1. Create a Quarkus Project with REST and JSON support

Create a new Quarkus Project with the REST Jackson extension. Execute the following command in your project directory.

quarkus create app com.ibm.developer:module-four \
  --extension=quarkus-rest-jackson

This creates a new project called module-four with the Quarkus REST extension already included. Adding JSON support means that your endpoints can speak the same format that most modern applications and APIs use, making integration easy.

Step 2. Modify the example resource class

Open the src/main/java/org/acme/GreetingResource.java file and replace the content with the following:

package com.ibm.developer;

import java.util.Map;

import org.eclipse.microprofile.config.inject.ConfigProperty;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/greeting")
public class GreetingResource {

    @ConfigProperty(name = "greeting.message", defaultValue = "hello, Quarkus!")
    String message;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Map<String, String> greeting() {
        return Map.of("message", message);
    }
}

The class is a REST resource, which means it defines an HTTP endpoint that clients can call.

The @Path("/greeting") annotation makes the class available at the URL /greeting.

The @ConfigProperty annotation injects a value from the configuration (application.properties). If no value is set, it falls back to the default "hello, Quarkus!".

The greeting() method is exposed as an HTTP GET endpoint because of @GET.

The method produces JSON (@Produces(MediaType.APPLICATION_JSON)), so responses are automatically serialized to JSON.

The method returns a simple JSON object with one key/value pair: "message": "<configured text>".

Open src/main/resources/application.properties and add:

greeting.message=hello from configuration!
quarkus.http.port=8081

In this file, we:

  • Defined a custom message for our greeting endpoint.
  • Changed the HTTP port from the default 8080 to 8081.

Now, start the app in dev mode:

quarkus dev

Then, call the endpoint:

curl http://localhost:8081/greeting

Your application runs on port 8081 and responds with the custom greeting message.

The application.properties file is the central place to manage your app’s settings. Small changes here can completely alter how your app runs, without touching code.

Why external configuration matters

Applications need to change their behavior depending on where they run. For example:

  • In development, you might use an in-memory database.
  • In test, you want to start services automatically (Dev Services).
  • In production, you connect to a real PostgreSQL cluster.

If you hardcode these values in code, you will constantly recompile and risk mistakes. By using configuration files and profiles, Quarkus makes it easy to adjust behavior without touching the source code.

Step 3. Work with profiles

Profiles let you switch between environments easily. Instead of one big config file, you have context-aware settings that Quarkus activates automatically.

Quarkus supports three main profiles by default:

  • dev runs when you start quarkus dev.
  • test runs during ./mvnw test.
  • prod runs when you build and package your app.

You can set different values per profile by prefixing the property:

%dev.greeting.message=hello from Dev Profile!
%test.greeting.message=hello from Test Profile!
%prod.greeting.message=hello from Prod Profile!

When you call /greeting in dev mode, you will see the dev message. During tests, the test message is used.

Step 4. Override configuration with environment variables

In real deployments, you often don’t want to touch the JAR file or its properties file. Quarkus allows overriding configuration with environment variables.

For example, run:

export QUARKUS_HTTP_PORT=9090

quarkus dev

Now your app runs on port 9090, even though application.properties says 8081. Why this matters: This makes it easy to adjust settings per environment, especially in containers and Kubernetes. You can deploy the same application image to many places but configure it differently at runtime.

Step 5. Explore advanced configuration options

Knowing that configuration is flexible in Quarkus helps you plan ahead. You start simple with application.properties, and later you can grow into advanced scenarios without changing your whole application.

So far, you’ve worked with the basics: application.properties, profiles, and environment variables. But Quarkus supports much more. You can:

These are powerful options when your applications grow more complex. You don’t need them yet, but it’s good to know they exist.

Summary

You learned how Quarkus uses external configuration through application.properties to make applications portable across environments, and how profiles (dev, test, prod) enable context-aware settings that activate automatically. You also discovered that environment variables can override configuration at runtime, allowing you to deploy the same application image to different environments with different settings, which is especially valuable in containerized and Kubernetes deployments.


04 December 2025

Legend