Quarkus - Configuring Your Application
Hardcoded values in your code is 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 3.5.3+
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 https://github.com/quarkusio/quarkus-quickstarts.git
, or download an archive.
The solution is located in the application-configuration
directory.
Creating the Maven project
First, we need a new project. Create a new project with the following command:
mvn io.quarkus:quarkus-maven-plugin:0.12.0:create \
-DprojectGroupId=org.acme \
-DprojectArtifactId=application-configuration \
-DclassName="org.acme.config.GreetingResource" \
-Dpath="/greeting"
It generates:
-
the Maven structure
-
a landing page accessible on
http://localhost:8080
-
example
Dockerfile
files for bothnative
andjvm
modes -
the application configuration file
-
an
org.acme.config.GreetingResource
resource -
an associated test
Injecting configuration value
Quarkus uses MicroProfile Config to inject the configuration in the application.
The injection uses the @ConfigProperty
annotation.
@ConfigProperty(name = "greeting.message")
private String message;
Edit the org.acme.config.GreetingResource
, and introduce the 3 following configuration properties:
@ConfigProperty(name = "greeting.message")
private String message;
@ConfigProperty(name = "greeting.suffix", defaultValue="!")
private String suffix;
@ConfigProperty(name = "greeting.name")
private Optional<String> name;
When injecting a configured value, you can use @Inject @ConfigProperty(…) or just @ConfigProperty(…) .
The @Inject annotation is not necessary for members annotated with @ConfigProperty , a behavior which differs from MicroProfile Config
|
If you do not provide a value for the first property, it will have a null
value.
The second property injects the given default value if the configuration file does not provide a value.
The third property is optional. The injected Optional
is empty as the configuration file does not provide a value.
Now, modify the hello
method to use the injected properties:
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return message + " " + name.orElse("world") + suffix;
}
Create the configuration
By default, Quarkus reads application.properties
.
Edit the src/main/resources/application.properties
with the following content:
# Your configuration properties
greeting.message = hello
greeting.name = quarkus
Once set, check the application with:
$ curl http://localhost:8080/greeting
hello quarkus!
If the application requires configuration values and these values are not set, an error is thrown. So you can quickly know when your configuration is complete. |
Update the test
We also need to update the functional test to reflect the changes made to endpoint.
Edit the src/test/java/org/acme/config/GreetingResourceTest.java
file and change the content of the testHelloEndpoint
method to:
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
.
Overriding properties at runtime
Quarkus does much of its configuration and bootstrap at build time. Most properties will then be read and set during the build time step. To change them, make sure to repackage your application.
./mvnw clean package
Extensions do define some properties as overridable at runtime. A canonical example is the database URL, username and password which is only known specifically in your target environment. This is a tradeoff as the more runtime properties are available, the less build time prework Quarkus can do. The list of runtime properties is therefore lean.
You can override these runtime properties with the following mechanisms (in decreasing priority):
-
using system properties:
-
for a runner jar:
java -Dquarkus.datasource.password=youshallnotpass -jar target/myapp-runner.jar
-
for a native executable:
./target/myapp-runner -Dquarkus.datasource.password=youshallnotpass
-
-
using environment variables:
-
for a runner jar:
export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; java -jar target/myapp-runner.jar
-
for a native executable:
export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; ./target/myapp-runner
-
Environment variables names are following the conversion rules of Eclipse MicroProfile |
More info on how to configure
Quarkus relies on Eclipse MicroProfile and inherit its features.
There are converters that convert your property file content from String
to typed Java types. See the list in the specification.