Learn Quarkus - Configuration & Profiles

#Introduction

A good application doesn't hardcode configuration values in code. Ports, database URLs, credentials, and feature toggles should live outside the code so the application can run in many environments without recompiling.

Episode 8 covers the Quarkus configuration system thoroughly: application.properties and application.yaml, profiles for different environments, externalized config from environment variables, secrets, and config maps, as well as configuration management best practices in production.

#Configuration with application.properties and application.yaml

#The application.properties Format

The application.properties file in src/main/resources is the most common way. Its format is key=value:

quarkus.http.port=8080
quarkus.application.name=belajar-quarkus
greeting.message=Halo dari properties
quarkus.log.level=INFO

Custom values like greeting.message can be read from code using @ConfigProperty:

Reading config from code

import jakarta.enterprise.context.ApplicationScoped;
import org.eclipse.microprofile.config.inject.ConfigProperty;
 
@ApplicationScoped
public class GreetingService {
 
    @ConfigProperty(name = "greeting.message")
    String message;
 
    public String sapa() {
        return message;
    }
}

@ConfigProperty(name = "greeting.message") injects the config value directly into the field. If the key doesn't exist and there's no default, the application fails to start — a good behavior that prevents typos.

#The application.yaml Format

Quarkus supports YAML once the quarkus-config-yaml extension is added:

./mvnw quarkus:add-extension -Dextensions=config-yaml

Then create src/main/resources/application.yaml:

quarkus:
  http:
    port: 8080
  application:
    name: belajar-quarkus
greeting:
  message: Halo dari YAML

YAML is easier to read for hierarchical configuration. The command ./mvnw quarkus:add-extension -Dextensions=config-yaml must be run before using a YAML file.

#Environment-Specific Config and Profile Activation

#Quarkus Profiles

Quarkus has three built-in profiles: dev, test, and prod. Each profile is activated automatically according to the mode: dev during quarkus:dev, test during tests, and prod during build. Per-profile configuration uses the %<profile-name>. prefix:

greeting.message=default
 
%dev.greeting.message=Halo di development
%prod.greeting.message=Halo di produksi
quarkus.profile=prod

%dev.greeting.message only applies while the dev profile is active. Common values are written without a prefix. To override the profile manually, set quarkus.profile or the QUARKUS_PROFILE environment variable.

#Custom Profiles

You can also create custom profiles like %staging.. When the application is run with QUARKUS_PROFILE=staging, all keys prefixed with %staging. become active.

#Externalized Config from Env Vars and Secrets

#Environment Variable Mapping

Every config property is mapped to an environment variable by the rule: dots become underscores, all letters uppercase. For example, quarkus.http.port becomes QUARKUS_HTTP_PORT.

export QUARKUS_HTTP_PORT=9000
export GREETING_MESSAGE="Halo dari environment"
./mvnw quarkus:dev

Environment variables override values in application.properties. This is the most common way to deploy an application to various environments without changing files.

#Secrets and Security

Never store secrets in application.properties. Use environment variables, Kubernetes secrets, or a vault. The standard pattern in containers:

apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  DB_PASSWORD: "super-rahasia"

In application.properties, just reference the key name; the actual value comes from outside:

quarkus.datasource.password=${DB_PASSWORD}

The ${DB_PASSWORD} syntax takes the value from an environment variable at runtime — the value is never written in the repository.

#Configuration Management Best Practices for Production

#@ConfigMapping for Structured Configuration

For many custom configuration keys, use @ConfigMapping — an interface that groups keys in a type-safe way:

Structured config mapping

import io.smallrye.config.ConfigMapping;
import java.util.Optional;
 
@ConfigMapping(prefix = "greeting")
public interface GreetingConfig {
    String message();
    Optional<Integer> retries();
}

With YAML:

greeting:
  message: Halo dari mapping
  retries: 3

@ConfigMapping provides type-safe access, validation at startup, and easy testing. This is the recommended pattern for large applications.

#Golden Rules

• Separate changeable values from code; configuration lives outside the source.
• Use profiles for dev, test, staging, and prod.
• Secrets only through env vars, a secret store, or mounted files.
• Validate config at startup so misconfiguration is detected early.
• Document every custom key in the README or a config reference.

#Wrap-Up

Episode 8 makes your application's configuration flexible and secure: understanding application.properties and application.yaml, built-in and custom profiles, externalized config from environment variables, secret management, and @ConfigMapping for structured, type-safe configuration.

Key takeaways:

• application.properties and application.yaml are the center of configuration.
• The dev, test, and prod profiles activate different values automatically.
• The %dev., %test., %prod. prefixes separate configuration per environment.
• Env vars are mapped automatically: quarkus.http.port becomes QUARKUS_HTTP_PORT.
• Secrets should never be committed; use env vars or Kubernetes Secrets.
• ${ENV_VAR} reads external values at runtime.
• @ConfigMapping provides type-safe custom configuration.

In episode 9 we'll cover observability and health — SmallRye Health for readiness and liveness probes, SmallRye Metrics and Micrometer, logging and structured logging configuration, and custom health checks.