////
This guide 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
////
= Configuration Reference Guide

include::./attributes.adoc[]

:numbered:
:sectnums:
:sectnumlevels: 4
:toc:

IMPORTANT: The content of this guide has been revised and split into additional topics. Please check the <<additional-information,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 https://github.com/smallrye/smallrye-config[SmallRye Config] API an implementation of the
https://microprofile.io/project/eclipse/microprofile-config[MicroProfile Config] specification.

TIP: If you're looking for information how to make a Quarkus extension configurable then see the
<<writing-extensions.adoc#configuration,Writing Your Own Extension>> guide.

[[configuration-sources]]
== Config Sources

By default, Quarkus reads configuration properties from multiple sources (by descending ordinal):

1. (400) <<system-properties,System properties>>
2. (300) <<environment-variables,Environment variables>>
3. (295) <<env-file,.env>> file in the current working directory
4. (260) <<application-properties-file,Quarkus Application configuration file>> in `$PWD/config/application.properties`
5. (250) <<application-properties-file,Quarkus Application configuration file>> `application.properties` in classpath
6. (100) <<microprofile-config-properties-file,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.

image::config-sources.png[align=center,align=center,width=90%]

[[system-properties]]
=== 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`

[[environment-variables]]
=== 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`

NOTE: Environment variables names follow the conversion rules specified by
link:https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#default-configsources[MicroProfile Config].

[[env-file]]
=== `.env` file in the current working directory

..env
[source,properties]
----
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.

IMPORTANT: Environment variables in the `.env` file are not available via the `System.getenv(String)` API.

[[application-properties-file]]
=== 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. Each `application.properties` found is treated as a separate `ConfigSource`
and follow the same rules as every other source (override per property). 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`
[source,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.

NOTE: 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.

[[microprofile-config-properties-file]]
=== MicroProfile Config configuration file

The MicroProfile Config configuration file in `src/main/resources/META-INF/microprofile-config.properties`.

.`microprofile-config.properties`
[source,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.

TIP: It works in the exact same way as Quarkus Application configuration file `application.properties`. Recommendation
is to use Quarkus `application.properties`.

=== Additional Config Sources

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

* xref:config-yaml.adoc[YAML]
* xref:vault.adoc[HashiCorp Vault]
* xref:consul-config.adoc[Consul]
* xref:spring-cloud-config-client.adoc[Spring Cloud]

TIP: It is also possible to create a xref:config-extending-support.adoc#custom-config-source[Custom Config Source].

== Inject

Quarkus uses https://microprofile.io/project/eclipse/microprofile-config[MicroProfile Config] annotations to inject the
configuration properties in the application.

[source,java]
----
@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`.

NOTE: If the application attempts to inject a configuration property that is not set, an error is thrown.

[source,java]
----
@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`.

TIP: Use xref:config-mappings.adoc#config-mappings[Config Mappings] to group similar configuration properties.

=== Default Values

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 `javax.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:

* Primitives: `boolean`, `byte`, `short`, etc.
* Boxed primitives: `java.lang.Boolean`, `java.lang.Byte`, `java.lang.Short`, etc.
* 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:

[source,properties]
----
# 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:

[source,properties]
----
# 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:

[source,java]
----
@ConfigProperty(name = "server.address", defaultValue = "192.168.1.1")
InetAddress serverAddress;
----

== 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.

[source,java]
----
String databaseName = ConfigProvider.getConfig().getValue("database.name", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("database.name", String.class);
----

IMPORTANT: 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.

[[profiles]]
== 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.

=== 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`:

.application.properties
[source,properties]
----
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`:

..env
[source, properties]
----
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:

.application.properties
[source, properties]
----
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`.

=== 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

=== 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:

.application.properties
[source,properties]
----
quarkus.http.port=9090
%staging.quarkus.http.port=9999
----

Setting `quarkus.profile`  to `staging` will activate the `staging` profile.

IMPORTANT: Only a single profile may be active at a time.

[NOTE]
====
The `io.quarkus.runtime.configuration.ProfileManager#getActiveProfile` API provides a way to retrieve the active profile
programmatically.

Using `@ConfigProperty("quarkus.profile")` will *not* work properly.
====

=== 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:

.application.properties
[source,properties]
----
quarkus.http.port=9090
%staging.quarkus.http.test-port=9091
----

.application-staging.properties
[source,properties]
----
quarkus.http.port=9190
quarkus.http.test-port=9191
----

[NOTE]
====
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.
====

=== 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:

[source,properties]
----
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

=== Default Runtime Profile

The default Quarkus runtime profile is set to the profile used to build the application:

[source,bash]
----
./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.

[[property-expressions]]
== 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:

.application.properties
[source,properties]
----
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:

.application.properties
[source,properties]
----
%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:

.application.properties
[source,properties]
----
%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.

NOTE: Expressions lookups are performed in all config sources. The expression values and expansion values may reside in
different config sources.

=== With Environment Variables

Property Expressions also work with Environment Variables.

.application.properties
[source,properties]
----
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.

== Accessing a generating UUID

The default config source from Quarkus provides a random UUID value.
It generates the UUID at startup time.
So, the value changes between startups, including reloads in dev mode.

You can access the generated value using the `quarkus.uuid` property.
Use <<property-expressions, expressions>> to access it: `${quarkus.uuid}`.
For example, it can be useful to configure a Kafka client with a unique consumer group:

[source, properties]
----
mp.messaging.incoming.prices.group.id=${quarkus.uuid}
----

== 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.

.application.properties
[source,properties]
----
remote.host=quarkus.io
----

A lookup to `remote.host` with `-Dremote.host=` will throw an Exception, because the system property cleared the value.

[[indexed-properties]]
== 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:

.application.properties
[source,properties]
----
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.

IMPORTANT: Indexed Properties are not supported in Environment Variables.

[[configuring_quarkus]]
== 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 xref:all-config.adoc[documented and searchable].

[IMPORTANT]
====
As mentioned above, properties prefixed with `quarkus.` are effectively reserved for configuring Quarkus itself and its
extensions. Therefore, the `quarkus.` prefix should **never** be used for application specific properties.
====

=== 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.

TIP: The properties fixed at build time are marked with a lock icon (icon:lock[]) in the xref:all-config.adoc[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.

== 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 xref:reaugmentation.adoc[re-augmentation] can be used to rebuild the augmentation output for a different build time configuration.

[[additional-information]]
== Additional Information

* xref:config-yaml.adoc[YAML ConfigSource Extension]
* xref:vault.adoc[HashiCorp Vault ConfigSource Extension]
* xref:consul-config.adoc[Consul ConfigSource Extension]
* xref:spring-cloud-config-client.adoc[Spring Cloud ConfigSource Extension]
* xref:config-mappings.adoc[Mapping configuration to objects]
* xref:config-extending-support.adoc[Extending configuration support]

Quarkus relies on link:https://github.com/smallrye/smallrye-config/[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
link:https://smallrye.io/docs/smallrye-config/index.html[SmallRye Config documentation].

== Configuration Reference

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