The content of this guide has been revised and split into additional topics. Please check the Additional Information section. |
In this reference guide we’re going to describe various aspects of Quarkus configuration. A Quarkus application and Quarkus itself (core and extensions) are both configured via the same mechanism that leverages the SmallRye Config API an implementation of the MicroProfile Config specification.
If you’re looking for information how to make a Quarkus extension configurable then see the Writing Your Own Extension guide. |
1. Config Sources
By default, Quarkus reads configuration properties from multiple sources (by descending ordinal):
-
(400) System properties
-
(300) Environment variables
-
(295) .env file in the current working directory
-
(260) Quarkus Application configuration file in
$PWD/config/application.properties
-
(250) Quarkus Application configuration file
application.properties
in classpath -
(100) MicroProfile Config configuration file
META-INF/microprofile-config.properties
in classpath
The final configuration is the aggregation of the properties defined by all these sources. A configuration property
lookup starts by the highest ordinal configuration source available and works it way down to other sources until a
match is found. This means that any configuration property may override a value just by setting a different value in a
higher ordinal config source. For example, a property configured using an environment property overrides the value
provided using the application.properties
file.

1.1. System properties
System properties can be handed to the application through the -D
flag during startup. The following examples assign
the value youshallnotpass
to the attribute quarkus.datasource.password
.
-
For Quarkus dev mode:
./mvnw quarkus:dev -Dquarkus.datasource.password=youshallnotpass
-
For a runner jar:
java -Dquarkus.datasource.password=youshallnotpass -jar target/quarkus-app/quarkus-run.jar
-
For a native executable:
./target/myapp-runner -Dquarkus.datasource.password=youshallnotpass
1.2. Environment variables
-
For a runner jar:
export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; java -jar target/quarkus-app/quarkus-run.jar
-
For a native executable:
export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; ./target/myapp-runner
Environment variables names follow the conversion rules specified by MicroProfile Config. |
1.3. .env
file in the current working directory
QUARKUS_DATASOURCE_PASSWORD=youshallnotpass (1)
1 | The name QUARKUS_DATASOURCE_PASSWORD the same conversion rules used for Environment variables. |
For dev
mode, this file can be placed in the root of the project, but it is advised to not check it in to version
control.
Environment variables in the .env file are not available via the System.getenv(String) API.
|
1.4. Quarkus Application configuration file
The Quarkus Application configuration file is loaded from the classpath resources, for instance
src/main/resources/application.properties
, src/test/resources/application.properties
or from a jar
dependency that
contains an application.properties
entry. Additionally, the configuration file may also reside in
$PWD/config/application.properties
. The loading starts from the config folder and then classpath order
(application.properties
files in the application sources will have priority on the classloader loading order).
application.properties
greeting.message=hello (1)
quarkus.http.port=9090 (2)
1 | This is a user-defined configuration property. |
2 | This is a configuration property consumed by the quarkus-vertx-http extension. |
The config/application.properties is also available in dev mode. The file needs to be placed inside the build
tool output directory (target for Maven and build/classes/java/main for Gradle). Keep in mind however that any
cleaning operation from the build tool like mvn clean or gradle clean will remove the config directory as well.
|
1.5. MicroProfile Config configuration file
The MicroProfile Config configuration file in src/main/resources/META-INF/microprofile-config.properties
.
microprofile-config.properties
greeting.message=hello (1)
quarkus.http.port=9090 (2)
1 | This is a user-defined configuration property. |
2 | This is a configuration property consumed by the quarkus-vertx-http extension. |
It works in the exact same way as Quarkus Application configuration file application.properties . Recommendation
is to use Quarkus application.properties .
|
1.6. Additional Config Sources
Quarkus provides additional extensions which cover other configuration formats and stores:
It is also possible to create a Custom Config Source. |
2. Inject
Quarkus uses MicroProfile Config annotations to inject the configuration properties in the application.
@ConfigProperty(name = "greeting.message") (1)
String message;
1 | You can use @Inject @ConfigProperty or just @ConfigProperty . The @Inject annotation is not necessary for
members annotated with @ConfigProperty . |
If the application attempts to inject a configuration property that is not set, an error is thrown. |
@ConfigProperty(name = "greeting.message") (1)
String message;
@ConfigProperty(name = "greeting.suffix", defaultValue="!") (2)
String suffix;
@ConfigProperty(name = "greeting.name")
Optional<String> name; (3)
1 | If you do not provide a value for this property, the application startup fails with javax.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message . |
2 | The default value is injected if the configuration does not provide a value for greeting.suffix . |
3 | This property is optional - an empty Optional is injected if the configuration does not provide a value for greeting.name . |
Use Config Mappings to group similar configuration properties. |
3. Programmatically access
The org.eclipse.microprofile.config.ConfigProvider.getConfig()
API allows to access the Config API programmatically.
This API is mostly useful in situations where CDI injection is not available.
String databaseName = ConfigProvider.getConfig().getValue("database.name", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("database.name", String.class);
Do not use System.getProperty(String) or System.getEnv(String) to retrieve configuration values. These
APIs are not configuration aware and do not support the features described in this guide.
|
4. Profiles
We often need to configure differently our application depending on the target environment. For example, the local development environment may be different from the production environment.
Configuration Profiles allow for multiple configurations in the same file or separate files and select between them via a profile name.
4.1. Profile in the property name
To be able to set properties with the same name, each property needs to be prefixed with a percentage sign %
followed
by the profile name and a dot .
in the syntax %{profile-name}.config.name
:
quarkus.http.port=9090
%dev.quarkus.http.port=8181
The Quarkus HTTP port will be 9090. If the dev
profile is active it will be 8181.
Profiles in the .env
file follow the syntax _{PROFILE}_CONFIG_KEY=value
:
QUARKUS_HTTP_PORT=9090
_DEV_QUARKUS_HTTP_PORT=8181
If a profile does not define a value for a specific attribute, the default (no profile) value is used:
bar=”hello”
baz=”bonjour”
%dev.bar=”hallo”
With the dev
profile enabled, the property bar
has the value hallo
, but the property baz
has the value
bonjour
. If the prod
profile is enabled, bar
has the value hello
(as there is no specific value for the prod
profile), and baz
the value bonjour
.
4.2. Default Profiles
By default, Quarkus provides three profiles, that activate automatically in certain conditions:
-
dev - Activated when in development mode (i.e.
quarkus:dev
) -
test - Activated when running tests
-
prod - The default profile when not running in development or test mode
4.3. Custom Profiles
It is also possible to create additional profiles and activate them with the quarkus.profile
configuration property. A
single config property with the new profile name is the only requirement:
quarkus.http.port=9090
%staging.quarkus.http.port=9999
Setting quarkus.profile
to staging
will activate the staging
profile.
Only a single profile may be active at a time. |
The Using |
4.4. Profile aware files
In this case, properties for a specific profile may reside in an application-{profile}.properties
named file. The previous
example may be expressed as:
quarkus.http.port=9090
%staging.quarkus.http.test-port=9091
quarkus.http.port=9190
quarkus.http.test-port=9191
In this style, the configuration names in the profile aware file do not need to be prefixed with the profile name. Properties in the profile aware file have priority over profile aware properties defined in the main file. |
4.5. Parent Profile
A Parent Profile adds one level of hierarchy to the current profile. The configuration quarkus.config.profile.parent
accepts a single profile name.
When the Parent Profile is active, if a property cannot be found in the current active Profile, the config lookup fallbacks to the Parent Profile. Consider:
quarkus.profile=dev
quarkus.config.profile.parent=common
%common.quarkus.http.port=9090
%dev.quarkus.http.ssl-port=9443
quarkus.http.port=8080
quarkus.http.ssl-port=8443
Then
-
The active profile is
dev
-
The parent profile is
common
-
quarkus.http.port
is 9090 -
quarkus.http.ssl-port
is 9443
4.6. Default Runtime Profile
The default Quarkus runtime profile is set to the profile used to build the application:
./mvnw package -Pnative -Dquarkus.profile=prod-aws
./target/my-app-1.0-runner (1)
1 | The command will run with the prod-aws profile. This can be overridden using the quarkus.profile configuration. |
5. Property Expressions
Quarkus provides property expressions expansion on configuration values. An expression string is
a mix of plain strings and expression segments, which are wrapped by the sequence ${ … }
.
These expressions are resolved when the property is read. So if the configuration property is build time the property expression will be resolved at build time. If the configuration property is overridable at runtime it will be resolved at runtime.
Consider:
remote.host=quarkus.io
callable.url=https://${remote.host}/
The resolved value of the callable.url
property is https://quarkus.io/
.
Another example would be defining different database servers by profile:
%dev.quarkus.datasource.jdbc.url=jdbc:mysql://localhost:3306/mydatabase?useSSL=false
quarkus.datasource.jdbc.url=jdbc:mysql://remotehost:3306/mydatabase?useSSL=false
can be simplified to:
%dev.application.server=localhost
application.server=remotehost
quarkus.datasource.jdbc.url=jdbc:mysql://${application.server}:3306/mydatabase?useSSL=false
Additionally, the Expression Expansion engine supports the following segments:
-
${expression:value}
- Provides a default value after the:
if the expansion doesn’t find a value. -
${my.prop${compose}}
- Composed expressions. Inner expressions are resolved first. -
${my.prop}${my.prop}
- Multiple expressions.
If an expression cannot be expanded and no default is supplied a NoSuchElementException
is thrown.
Expresions lookups are performed in all config sources. The expression values and expansion values may reside in different config sources. |
5.1. With Environment Variables
Property Expressions also work with Environment Variables.
remote.host=quarkus.io
application.host=${HOST:${remote.host}}
This will expand the HOST
environment variable and use the value of the property remote.host
as the default value
if HOST
is not set.
6. Clearing properties
Run time properties which are optional, and which have had values set at build time or which have a default value, may be explicitly cleared by assigning an empty string to the property. Note that this will only affect runtime properties, and will only work with properties whose values are not required.
remote.host=quarkus.io
A lookup to remote.host
with -Dremote.host=
will throw an Exception, because the system property cleared the value.
7. Indexed Properties
A config value which contains unescaped commas may be converted to Collection
. This works for simple cases, but it
becomes cumbersome and limited for more advanced cases.
Indexed Properties provide a way to use indexes in config property names to map specific elements in a Collection
type. Since the indexed element is part of the property name and not contained in the value, this can also be used to
map complex object types as `Collectionª elements. Consider:
my.collection=dog,cat,turtle
my.indexed.collection[0]=dog
my.indexed.collection[1]=cat
my.indexed.collection[2]=turtle
The indexed property syntax uses the property name and square brackets `[ ] with an index in between.
A call to Config#getValues("my.collection", String.class)
, will automatically create and convert a List<String>
that contains the values dog
, cat
and turtle
. A call to Config#getValues("my.indexed.collection", String.class)
returns the exact same result. If the same property name exists in both froms (regular and indexed), the regular
value has priority.
The indexed property is sorted by their index before being added to the target Collection
. Any gaps contained in the
indexes do not resolve to the target Collection
, which means that the Collection
result will store all values
without any gaps.
8. Generate Configuration
It is also possible to generate an example application.properties
with all known configuration properties:
./mvnw quarkus:generate-config
This creates a src/main/resources/application.properties.example
file that contains all the config options
exposed via the extensions currently present in the application. These options are commented out, and have their value
set to default swhen applicable. For example this HTTP port config entry will appear as:
#
# The HTTP port
#
#quarkus.http.port=8080
Rather than generating an example config file, you can also add these to you actual config file by setting the -Dfile
parameter:
./mvnw quarkus:generate-config -Dfile=application.properties
If a config option is already present it will not be added, so it is safe to run this after adding an extension to see which configurations are available.
9. Configuring Quarkus
Quarkus itself is configured via the same mechanism as your application. Quarkus reserves the quarkus.
namespace
for its own configuration. For example to configure the HTTP server port you can set quarkus.http.port
in
application.properties
. All the Quarkus configuration properties are documented and searchable.
As mentioned above, properties prefixed with |
9.1. Build Time configuration
Some Quarkus configurations only take effect during build time, meaning is not possible to change them at runtime. These configurations are still available at runtime but as read-only and have no effect in Quarkus behaviour. A change to any of these configurations requires a rebuild of the application itself to reflect changes of such properties.
The properties fixed at build time are marked with a lock icon () in the list of all configuration options. |
However, some extensions do define properties overridable at runtime. A simple example is the database URL, username and password which is only known specifically in your target environment, so they can be set and influence the application behaviour at runtime.
10. Change build time properties after your application has been published
If you are in the rare situation that you need to change the build time configuration after your application is built, then check out how re-augmentation can be used to rebuild the augmentation output for a different build time configuration.
11. Additional Information
Quarkus relies on SmallRye Config and inherits its features:
-
Additional
ConfigSource
s -
Additional
Converter
s -
Indexed properties
-
Parent profile
-
Interceptors for configuration value resolution
-
Relocate configuration properties
-
Fallback configuration properties
-
Logging
-
Hide secrets
For more information, please check the SmallRye Config documentation.
12. Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
Additional config locations to be loaded with the Config. The configuration support multiple locations separated by a comma and each must represent a valid |
list of string |
|
Accepts a single configuration profile name. If a configuration property cannot be found in the current active profile, the config performs the same lookup in the profile set by this configuration. |
string |