Re-augment a Quarkus Application
Quarkus application configuration may include two types of configuration options:
Build time options, handled during the application build time;
Runtime options, that may be adjusted after the application has been built but before it has been launched.
The augmentation is a phase of an application build process during which the byte code of the application is optimized according to the application build time configuration. Initialization steps that used to happen when an EAR file was deployed on a Jakarta EE server such as parsing static configuration, creating proxy instances, etc. now happen at augmentation time. CDI beans added after augmentation won’t work (because of the missing proxy classes) as well as build time properties (e.g.
quarkus.datasource.db-kind) changed after augmentation will be ignored. Build time properties are marked with a lock icon () in the list of all configuration options. It doesn’t matter if you use profiles or any other way to override the properties. The build time properties that were active during augmentation are baked into the build.
Re-augmentation is the process of recreating the augmentation output for a different build time configuration
Re-augmentation is useful in case the users of your application want to be able to change some of its build time properties. For instance changing the database driver or switching features on or off (e.g. OpenTracing or Config Consul). If there are only two or three build time properties that depend on the user environment, you may consider providing alternative builds of the application. However, in case there are more such properties you may prefer shipping a mutable jar instead and let your users re-augment the application for their environment. Please notice that you won’t be able to use native images with the package type
mutable-jar. Think of the consequences and what other options you have!
It is not a good idea to do re-augmentation at runtime unless you miss the good old times when starting up a server took several minutes and you could enjoy a cup of coffee until it was ready.
In order to run the augmentation steps you need the deployment JARs of the used Quarkus extensions. These JARs are only present in the
mutable-jar distribution. This means that you need to build your application with
mutable-jar distribution is the same as the
fast-jar distribution, except for the additional folder
quarkus-app/lib/deployment which contains the deployment JARs and their dependencies (and some class-loader configuration).
By default, you’ll get a warning if a build time property has been changed at runtime. You may set the
In order to re-augment your Quarkus application with different build time properties, start the application with the desired configuration plus the
quarkus.launch.rebuild system property set to
The following example changes the
mysql. For this to work the
mysql-extension must have been included in the build. Augmentation can only use extensions that were present during compile time.
java -jar -Dquarkus.launch.rebuild=true -Dquarkus.datasource.db-kind=mysql target/quarkus-app/quarkus-run.jar
It does not matter if you use system properties, environment variables, profiles, or an external config file. The current configuration will be used for augmentation (the content of
You may delete the directory
quarkus-app/lib/deployment to save some space in your ZIP distribution or Docker image (remember to use a multistage Docker build to avoid unnecessary layers). After deleting the
deployment directory, it is obviously not possible anymore to re-augment the application.