Overriding configuration properties via Maven pom.xml

[frederikb]

Hi,

I would like to clarify some behavior regarding configuration and Maven.

According to the documentation we can specify some properties such as quarkus.profile at build-time via Maven using various mechanisms, whereas the following precedence rules apply:

1. System properties set in the Quarkus Maven plugin configuration
2. Quarkus Maven plugin configuration properties
3. Project properties

It further states:

Whatever the approach is chosen, the profile can still be overridden with the quarkus.profile system property or the QUARKUS_PROFILE environment variable.

I've seen some mentions in the code which suggest that this behavior applies to all properties that start with quarkus..

This is further corroborated by other documentation and official examples, i.e. for quarkus.package.type or quarkus.container-image.build .

Is this correct?

And how do these precendence rules work when the respective configuration option has been defined in the application.properties. Will all of these mechanism override that value at build-time?

Does this only apply to build-time properties?

I would appreciate any (official) clarification.

[quarkus-bot[bot]]

/cc @quarkusio/devtools (maven)

[chberger]

@cescoffier @geoand Would be nice to get some clarification on this. Thanks!

[geoand]

This is one for @aloubyansky

[chberger]

@aloubyansky any chance to get an answer on this?

[aloubyansky]

According to the documentation we can specify some properties such as quarkus.profile at build-time via Maven using various mechanisms, whereas the following precedence rules apply:

1. System properties set in the Quarkus Maven plugin configuration

This configuration option sets system properties. In dev mode it passes all the configured properties as system properties to the process running the application in dev mode.
When packaging, it sets configured system properties unless a given property is already set. It has to be used with caution when packaging the app, i.e. I wouldn't recommend it unless there is a very strong reason to. This also isn't playing well with concurrent Maven builds.

2. Quarkus Maven plugin configuration properties
3. Project properties

This precedence is correct.

It further states:

Whatever the approach is chosen, the profile can still be overridden with the quarkus.profile system property or the QUARKUS_PROFILE environment variable.

I've seen some mentions in the code which suggest that this behavior applies to all properties that start with quarkus..

This code snippet collects quarkus.* properties from the POM and passes them on to the config builder.

This is further corroborated by other documentation and official examples, i.e. for quarkus.package.type or quarkus.container-image.build .

Is this correct?

Yes.

And how do these precendence rules work when the respective configuration option has been defined in the application.properties. Will all of these mechanism override that value at build-time?

application.properties have a higher priority than POM properties but lower than system properties. The hierarchy is documented in https://quarkus.io/guides/config-reference#configuration-sources

Does this only apply to build-time properties?

It applies to all the properties.

FYI @radcortez in case you want to add more info, thanks.

[radcortez]

You explained it perfectly :)

[frederikb]

Thanks, @aloubyansky for taking the time! Much appreciated!

[…] When packaging, it sets configured system properties unless a given property is already set.

What does that mean? In which cases is a property considered to be already set? Shouldn't a system property have a higher precedence than a property set in the application.properties, as discussed below?

application.properties have a higher priority than POM properties but lower than system properties. The hierarchy is documented in https://quarkus.io/guides/config-reference#configuration-sources

Understood. For me there is a missing link in the documentation between POM properties and the configuration hierarchy documented in the reference guide:

1. POM properties are never explicitly introduced as a valid property source for setting quarkus. properties (only implictly through examples )
2. The hierarchy does not mention POM properties at all (most likely because it is build-tool specific?), nor is the precendence rule between POM properties and application.properties stated anywhere

In other words: your explanation makes a lot of sense and correborates the observed behavior, but as application developer I would have liked to see it documented.

FYI @chberger

[aloubyansky]

[…] When packaging, it sets configured system properties unless a given property is already set.

What does that mean? In which cases is a property considered to be already set? Shouldn't a system property have a higher precedence than a property set in the application.properties, as discussed below?

That phrase is relevant to setting system properties only. I.e. a system property configured in the quarkus-maven-plugin config will be set unless a system property with that name is already set to some value. application.properties and other config sources aren't consulted at this point.

application.properties have a higher priority than POM properties but lower than system properties. The hierarchy is documented in https://quarkus.io/guides/config-reference#configuration-sources

Understood. For me there is a missing link in the documentation between POM properties and the configuration hierarchy documented in the reference guide:

1. POM properties are never explicitly introduced as a valid property source for setting quarkus. properties (only implictly through examples )
2. The hierarchy does not mention POM properties at all (most likely because it is build-tool specific?), nor is the precendence rule between POM properties and application.properties stated anywhere

In other words: your explanation makes a lot of sense and correborates the observed behavior, but as application developer I would have liked to see it documented.

The referenced guide is probably targeting runtime. POM properties (aka build system properties) are available only at build time. But that's a valid remark. We should document it better. Would you like to submit a contribution? :)