////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////
= Quarkus - Configuring Your Application

include::./attributes.adoc[]

:toc:

Hardcoded values in your code are a _no go_ (even if we all did it at some point ;-)).
In this guide, we learn how to configure your application.

== Prerequisites

To complete this guide, you need:

* between 5 and 10 minutes
* an IDE
* JDK 1.8+ installed with `JAVA_HOME` configured appropriately
* Apache Maven {maven-version}

== Solution

We recommend that you follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].

The solution is located in the `config-quickstart` {quickstarts-tree-url}/config-quickstart[directory].

== Creating the Maven project

First, we need a new project. Create a new project with the following command:

[source,bash,subs=attributes+]
----
mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=config-quickstart \
    -DclassName="org.acme.config.GreetingResource" \
    -Dpath="/greeting"
cd config-quickstart
----

It generates:

* the Maven structure
* a landing page accessible on `http://localhost:8080`
* example `Dockerfile` files for both `native` and `jvm` modes
* the application configuration file
* an `org.acme.config.GreetingResource` resource
* an associated test

== Create the configuration

By default, Quarkus reads configuration properties from <<config-reference.adoc#configuration_sources,several sources>>.
For the purpose of this guide, we will use an application configuration file located in `src/main/resources/application.properties`.
Edit the file with the following content:

[source,properties]
----
# Your configuration properties
greeting.message = hello
greeting.name = quarkus
----

== Injecting configuration properties

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`.
This behavior differs from https://microprofile.io/project/eclipse/microprofile-config[MicroProfile Config].

NOTE: If the application attempts to inject a configuration property that is not set, an error is thrown.
So you can quickly know when your configuration is complete.

Edit the `org.acme.config.GreetingResource`, and introduce the following configuration properties:

[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`.

Now, modify the `hello` method to use the injected properties:

[source,java]
----
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
    return message + " " + name.orElse("world") + suffix;
}
----

Once set, check the application with:

[source,shell]
----
$ curl http://localhost:8080/greeting
hello quarkus!
----

TIP: As an alternative to injecting multiple related configuration values, you can also use the `@io.quarkus.arc.config.ConfigProperties` annotation to group these properties together. 
See the <<config-reference.adoc#using_configproperties,Configuration Reference Guide>> for more information.

== Update the test

We also need to update the functional test to reflect the changes made to the endpoint.
Edit the `src/test/java/org/acme/config/GreetingResourceTest.java` file and change the content of the `testHelloEndpoint` method to:

[source,java]
----
package org.acme.config;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;

@QuarkusTest
public class GreetingResourceTest {

    @Test
    public void testHelloEndpoint() {
        given()
          .when().get("/greeting")
          .then()
             .statusCode(200)
             .body(is("hello quarkus!")); // Modified line
    }

}
----

== Package and run the application

Run the application with: `./mvnw compile quarkus:dev`.
Open your browser to http://localhost:8080/greeting.

Changing the configuration file is immediately reflected.
You can add the `greeting.suffix`, remove the other properties, change the values, etc.

As usual, the application can be packaged using `./mvnw clean package` and executed using the `-runner.jar` file.
You can also generate the native executable with `./mvnw clean package -Pnative`.

== Programmatically access the configuration

You can also access the configuration programmatically.
It can be handy to achieve dynamic lookup, or retrieve configured values from classes that are neither CDI beans or JAX-RS resources.

You can access the configuration programmatically using `org.eclipse.microprofile.config.ConfigProvider.getConfig()` such as in:

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

== Configuration Profiles

Quarkus supports the notion of configuration profiles. 
These allow you to have multiple configuration values in the same file and select between them via a profile name.

The syntax for this is `%{profile}.config.key=value`. For example if I have the following:

[source,properties]
----
quarkus.http.port=9090
%dev.quarkus.http.port=8181
----

Then the Quarkus HTTP port will be 9090, unless the `dev` profile is active, in which case it will be 8181.

See the <<config-reference.adoc#configuration_profiles,Configuration Reference Guide>> for more information about configuration profiles.

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

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

In the previous examples using `quarkus.message` instead of `greeting.message` would result in unexpected behavior.
====

Quarkus does much of its configuration and bootstrap at build time and some configuration properties are read and used during the build.
These properties are _fixed at build time_ and it's not possible to change them at runtime.
You always need to repackage your application in order to reflect changes of such properties.

TIP: The properties fixed at build time are marked with a lock icon (icon:lock[]) in the link:all-config[list of all configuration options].

However, some extensions do define properties _overridable at runtime_.
A canonical example is the database URL, username and password which is only known specifically in your target environment.

1. System properties
2. Environment variables
3. An environment file named `.env` placed in the current working directory
4. A configuration file placed in `$PWD/config/application.properties`

See the <<config-reference.adoc#configuring_quarkus,Configuration Reference Guide>> for more information.
