Additionally to the default config locations, Quarkus provides a way to scan additional locations for configuration properties files.

The quarkus.config.locations configuration property accepts multiple locations separated by a comma , and each must represent a valid URI . The supported URI schemes are:

All loaded sources use the same ordinal of the source that found the quarkus.config.locations configuration property. For instance, if quarkus.config.locations is set as a system property, then all loaded sources have their ordinals set to 400 (system properties use 400 as their ordinal). The ordinal may be overridden directly for each config source by setting the config_ordinal property and the ordinal value. The config_ordinal property only affects the ordinal of the source in which is being set. Sources are sorted first by their ordinal, then by location order, and finally by loading order.

Quarkus provides additional extensions which cover other configuration formats and stores:

If a property is associated with a default value (by way of the defaultValue attribute), and no configuration value is supplied for the property, then rather than throwing a jakarta.enterprise.inject.spi.DeploymentException , the default value will be used. The defaultValue value is expressed as a String , and uses the same conversion mechanism used to process configuration values. Several Built-in Converters already exist for primitives, boxed primitives, and other classes; for example:

Optional containers: java.util.Optional , java.util.OptionalInt , java.util.OptionalLong , and java.util.OptionalDouble

Java enum types

JSR 310 java.time.Duration

JDK networking java.net.SocketAddress , java.net.InetAddress , etc.

As you might expect, these converters are org.eclipse.microprofile.config.spi.Converter implementations. Therefore, these converters comply with the Microprofile or custom implementation providers expression rules like:

Boolean values will be true in cases "true", "1", "YES", "Y" "ON". Otherwise, value will be interpreted as false

For float and double values the fractional digits must be separated by a dot .

Note that when a combination of Optional* types and the defaultValue attribute are used, the defined defaultValue will still be used and if no value is given for the property, the Optional* will be present and populated with the converted default value. However, when the property is explicitly empty, the default value is not used and the Optional will be empty. Consider this example:

# missing value, optional property
greeting.name=

In this case, since greeting.name was configured to be Optional* up above, the corresponding property value will be an empty Optional and execution will continue normally. This would be the case even if there was a default value configured: the default value is not used if the property is explicitly cleared in the configuration.

On the other hand, this example:

# missing value, non-optional
greeting.suffix=

will result in a java.util.NoSuchElementException: SRCFG02004: Required property greeting.message not found on startup and the default value will not be assigned.

Below is an example of a Quarkus-supplied converter:

@ConfigProperty(name = "server.address", defaultValue = "192.168.1.1")
InetAddress serverAddress;

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);

We often need to configure our application differently 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.

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 .

By default, Quarkus provides three profiles, that activate automatically in certain conditions:

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.

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.

Do not use profile aware files to set quarkus.profile or quarkus.test.profile . This will not work because the profile is required in advance to load the profile aware files.

A profile aware file is only loaded if the unprofiled application.properties is also available in the same location and the file extension matches between the files. This is required to keep a consistent loading order and pair all the resources together.

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

Do not use Profile aware files to set quarkus.config.profile.parent . This will not work because the profile is required in advance to load the profile aware files.

Multiple Profiles may be active at the same time. The configuration quarkus.profile accepts a comma-separated list of profile names: quarkus.profile=common,dev . Both common and dev are separate profiles.

When multiple profiles are active, the rules for profile configuration are the same. If two profiles define the same configuration, then the last listed profile has priority. Consider:

quarkus.profile=common,dev
my.prop=1234
%common.my.prop=1234
%dev.my.prop=5678
%common.commom.prop=common
%dev.dev.prop=dev
%test.test.prop=test

It is also possible to define multiple profile properties, with a comma-separated list of profile names. If the same property name exists in multiple profile properties then, the property name with the most specific profile wins:

quarkus.profile=dev
%prod,dev.my.prop=1234
%dev.my.prop=5678
%prod,dev.another.prop=1234

Multiple profiles priority work in reverse order. With quarkus.profile=common,dev , Quarkus first checks the dev profile and then the common profile.

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}/

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.

A secret configuration may be expressed as ${handler::value} , where the handler is the name of a io.smallrye.config.SecretKeysHandler to decode or decrypt the value . Consider:

my.secret=${aes-gcm-nopadding::DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg}
# the encryption key required to decode the secret. It can be set in any source.
smallrye.config.secret-handler.aes-gcm-nopadding.encryption-key=somearbitrarycrazystringthatdoesnotmatter

A lookup to my.secret will use the SecretKeysHandler name aes-gcm-nopadding to decode the value DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg .

Some Quarkus configurations only take effect during build time, meaning it 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.

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.

Given that configuration sources usually provide more options than actually used during the build, it might be useful to know which configuration options have actually been used during a Quarkus build process.

Setting quarkus.config-tracking.enabled to true will enable a configuration interceptor that will record every configuration option that was read during the build process along with their values. The resulting report will be stored in ${project.basedir}/.quarkus/quarkus-prod-config-dump by default. The target file could be configured using the following options:

quarkus.config-tracking.directory - directory in which the configuration dump should be stored, the default is ${project.basedir}/.quarkus

quarkus.config-tracking.file-prefix - file name prefix, the default value is quarkus

quarkus.config-tracking.file-suffix - file name suffix, the default value is -config-dump

quarkus.config-tracking.file - path to a file in which the configuration dump should be stored. This option supersedes the file-prefix and file-suffix options. Also supersedes the value of quarkus.config-tracking.directory , unless the value is a relative path.

The prod part of the quarkus-prod-config-dump file name refers to the Quarkus build mode, indicating that the dump was taken for the production build.

Configuration tracker could be instructed to exclude some of the options from the report by configuring quarkus.config-tracking.exclude with a comma-separated list of configuration option names that should be filtered out.

Configuration options with absolute path values that begin with a user home directory are, by default, transformed with Unix home directory alias '~' replacing the user home directory part and using / as a path element separator.

This transformation can be disabled by setting quarkus.config-tracking.use-user-home-alias-in-paths to false .

Configuration values can be hashed using SHA-512 algorithm before they are written to a file. Configuration option names whose values should be hashed can be configured in quarkus.config-tracking.hash-options as a comma separated list.

While quarkus.config-tracking.enabled enables effective build time configuration report generation, there is also a way to check whether the values stored in that report have changed before the next build of the project is launched.

Maven projects could add the following goal to their quarkus-maven-plugin configuration:

      <plugin>
        <groupId>${quarkus.platform.group-id}</groupId>
        <artifactId>quarkus-maven-plugin</artifactId>
        <version>${quarkus.platform.version}</version>
        <extensions>true</extensions>
        <executions>
          <execution>
            <id>track-prod-config-changes</id>
            <phase>process-resources</phase>
            <goals>
              <goal>track-config-changes</goal>
            </goals>
          </execution>
          <!-- other executions would follow below -->

The track-config-changes goal looks for ${project.basedir}/.quarkus/quarkus-prod-config-dump (file name and directory are configurable) and, if the file already exists, checks whether the values stored in the config dump have changed. It will log the changed options and save the current values of each of the options present in ${project.basedir}/.quarkus/quarkus-prod-config-dump in ${project.basedir}/target/quarkus-prod-config.check (the target file name and location can be configured). If the build time configuration has not changed since the last build both ${project.basedir}/.quarkus/quarkus-prod-config-dump and ${project.basedir}/.quarkus/quarkus-prod-config-dump will be identical.

In addition to dumping configuration values, track-config-changes goal also dumps all the Quarkus application dependencies, including Quarkus build time dependencies. This file could be used to check whether Quarkus build classpath has changed since the previous run, for instance together with Develocity’s ability to checksum a classpath. By default, the list of dependencies will be stored under target/quarkus-prod-dependencies.txt file. A different location could be configured using plugin parameters.

By default, track-config-changes looks for the configuration recorded during previous build and does nothing if it’s not found. Enabling dumpCurrentWhenRecordedUnavailable parameter will make it dump the current build configuration options taking into account quarkus.config-tracking.* configuration.

Unlike the build configuration options recorded during the quarkus:build goal, configuration options saved by quarkus:track-config-changes with dumpCurrentWhenRecordedUnavailable enabled will include all the build configuration options exposed by a org.eclipse.microprofile.config.Config instance. Which means this report may include some build configuration options that will not be used by the Quarkus application build process but also may be missing some build configuration options since MicroProfile Config specification allows configuration sources not to expose all the property names they provide to users.