0
# Configuration
1

2
Quarkus provides a comprehensive configuration system that handles both build-time and runtime configuration with type-safe binding, validation, and environment-specific overrides. The configuration system supports multiple sources including properties files, environment variables, system properties, and programmatic configuration.
3

4
## Core Imports
5

6
```java
7
// Configuration readers and generators
8
import io.quarkus.deployment.configuration.BuildTimeConfigurationReader;
9
import io.quarkus.deployment.configuration.RunTimeConfigurationGenerator;
10
import io.quarkus.deployment.configuration.ClassLoadingConfig;
11

12
// Configuration build items
13
import io.quarkus.deployment.builditem.ConfigurationBuildItem;
14
import io.quarkus.deployment.builditem.StaticInitConfigSourceProviderBuildItem;
15
import io.quarkus.deployment.builditem.RunTimeConfigurationDefaultBuildItem;
16
import io.quarkus.deployment.builditem.SystemPropertyBuildItem;
17

18
// Configuration definition types
19
import io.quarkus.deployment.configuration.definition.RootDefinition;
20
import io.quarkus.deployment.configuration.definition.ClassDefinition;
21
import io.quarkus.deployment.configuration.definition.GroupDefinition;
22

23
// Configuration mapping and tracking
24
import io.quarkus.deployment.configuration.matching.ConfigPatternMap;
25
import io.quarkus.deployment.configuration.tracker.ConfigTrackingWriter;
26

27
// Runtime configuration types
28
import io.quarkus.runtime.configuration.ConfigBuilder;
29
import io.quarkus.runtime.configuration.ConfigurationException;
30

31
// SmallRye Config integration
32
import io.smallrye.config.Config;
33
import io.smallrye.config.ConfigMapping;
34
import io.smallrye.config.ConfigMappingContext;
35
import io.smallrye.config.WithDefault;
36
import io.smallrye.config.WithName;
37
```
38

39
## Configuration Readers and Generators
40

41
### BuildTimeConfigurationReader
42

43
Reads and processes build-time configuration from various sources.
44

45
```java { .api }
46
class BuildTimeConfigurationReader {
47
    /**
48
     * Reads build-time configuration from application sources
49
     */
50
    static RunTimeConfigurationGenerator.ReadResult readConfiguration(
51
        Path applicationRoot,
52
        Path outputDirectory,
53
        ConfigMappingContext configMappingContext,
54
        LaunchMode launchMode
55
    );
56
    
57
    /**
58
     * Reads configuration with custom sources and converters
59
     */
60
    static RunTimeConfigurationGenerator.ReadResult readConfiguration(
61
        Path applicationRoot,
62
        Path outputDirectory,
63
        ConfigMappingContext configMappingContext,
64
        LaunchMode launchMode,
65
        List<ConfigSourceProvider> configSourceProviders,
66
        List<Converter<?>> converters
67
    );
68
}
69
```
70

71
### RunTimeConfigurationGenerator
72

73
Generates runtime configuration setup code.
74

75
```java { .api }
76
class RunTimeConfigurationGenerator {
77
    /**
78
     * Generated configuration class name
79
     */
80
    static final String CONFIG_CLASS_NAME = "io.quarkus.runtime.generated.Config";
81
    static final String CONFIG_STATIC_NAME = "io.quarkus.runtime.generated.StaticInitConfig";
82
    static final String CONFIG_RUNTIME_NAME = "io.quarkus.runtime.generated.RunTimeConfig";
83
    
84
    /**
85
     * Method descriptors for generated configuration methods
86
     */
87
    static final MethodDescriptor C_CREATE_RUN_TIME_CONFIG;
88
    static final MethodDescriptor C_ENSURE_INITIALIZED;
89
    static final MethodDescriptor REINIT;
90
    static final MethodDescriptor C_READ_CONFIG;
91
    
92
    /**
93
     * Main configuration generation operation builder
94
     */
95
    static final class GenerateOperation implements AutoCloseable {
96
        /**
97
         * Creates a new generation operation builder
98
         */
99
        static Builder builder();
100
        
101
        @Override
102
        void close();
103
        
104
        static final class Builder {
105
            /**
106
             * Sets whether live reload is possible
107
             */
108
            Builder setLiveReloadPossible(boolean liveReloadPossible);
109
            
110
            /**
111
             * Sets the launch mode for configuration
112
             */
113
            Builder setLaunchMode(LaunchMode launchMode);
114
            
115
            /**
116
             * Sets the class output for generated classes
117
             */
118
            Builder setClassOutput(ClassOutput classOutput);
119
            
120
            /**
121
             * Sets the build-time configuration read result
122
             */
123
            Builder setBuildTimeReadResult(BuildTimeConfigurationReader.ReadResult result);
124
            
125
            /**
126
             * Sets additional types for configuration mapping
127
             */
128
            Builder setAdditionalTypes(List<Class<?>> additionalTypes);
129
            
130
            /**
131
             * Builds the generation operation
132
             */
133
            GenerateOperation build();
134
        }
135
    }
136
}
137
```
138

139
**Usage Example:**
140

141
```java
142
@BuildStep
143
void generateConfiguration(ApplicationArchivesBuildItem archives,
144
                          BuildProducer<GeneratedClassBuildItem> generatedClasses,
145
                          LaunchModeBuildItem launchMode,
146
                          List<ConfigClassBuildItem> configClasses) throws Exception {
147
    
148
    // Read build-time configuration
149
    BuildTimeConfigurationReader configReader = new BuildTimeConfigurationReader(deploymentClassLoader);
150
    BuildTimeConfigurationReader.ReadResult readResult = 
151
        configReader.readConfiguration(launchMode.getLaunchMode());
152
    
153
    // Set up class output for generated configuration classes
154
    ClassOutput classOutput = new ClassOutput() {
155
        @Override
156
        public void writeClass(boolean applicationClass, String className, byte[] data) {
157
            generatedClasses.produce(new GeneratedClassBuildItem(applicationClass, className, data));
158
        }
159
    };
160
    
161
    // Generate runtime configuration using builder pattern
162
    List<Class<?>> additionalTypes = configClasses.stream()
163
        .map(ConfigClassBuildItem::getConfigClass)
164
        .collect(Collectors.toList());
165
    
166
    try (RunTimeConfigurationGenerator.GenerateOperation operation = 
167
            RunTimeConfigurationGenerator.GenerateOperation.builder()
168
                .setLaunchMode(launchMode.getLaunchMode())
169
                .setLiveReloadPossible(launchMode.getLaunchMode() == LaunchMode.DEVELOPMENT)
170
                .setClassOutput(classOutput)
171
                .setBuildTimeReadResult(readResult)
172
                .setAdditionalTypes(additionalTypes)
173
                .build()) {
174
        
175
        // The GenerateOperation automatically generates the configuration classes
176
        // when built and properly closed via try-with-resources
177
    }
178
}
179
```
180

181
## Configuration Build Items
182

183
### ConfigurationBuildItem
184

185
Contains build-time configuration information.
186

187
```java { .api }
188
class ConfigurationBuildItem extends SimpleBuildItem {
189
    /**
190
     * Gets the build-time configuration instance
191
     */
192
    Config getConfig();
193
    
194
    /**
195
     * Gets configuration property names
196
     */
197
    Set<String> getPropertyNames();
198
    
199
    /**
200
     * Checks if a property is present
201
     */
202
    boolean hasProperty(String propertyName);
203
    
204
    /**
205
     * Gets a configuration value with type conversion
206
     */
207
    <T> Optional<T> getValue(String propertyName, Class<T> type);
208
}
209
```
210

211
### SystemPropertyBuildItem
212

213
Represents system properties to be set at runtime.
214

215
```java { .api }
216
class SystemPropertyBuildItem extends MultiBuildItem {
217
    /**
218
     * Creates a system property build item
219
     */
220
    SystemPropertyBuildItem(String key, String value);
221
    
222
    String getKey();
223
    String getValue();
224
}
225
```
226

227
### Configuration Source Build Items
228

229
```java { .api }
230
class StaticInitConfigSourceProviderBuildItem extends MultiBuildItem {
231
    /**
232
     * Creates a config source provider for static initialization
233
     */
234
    StaticInitConfigSourceProviderBuildItem(String configSourceProviderClassName);
235
    
236
    String getConfigSourceProviderClassName();
237
}
238

239
class RunTimeConfigurationDefaultBuildItem extends MultiBuildItem {
240
    /**
241
     * Sets a default value for runtime configuration
242
     */
243
    RunTimeConfigurationDefaultBuildItem(String key, String value);
244
    
245
    String getKey();
246
    String getValue();
247
}
248
```
249

250
**Usage Examples:**
251

252
```java
253
@BuildStep
254
void setupSystemProperties(BuildProducer<SystemPropertyBuildItem> systemProps) {
255
    systemProps.produce(new SystemPropertyBuildItem("quarkus.application.name", "my-app"));
256
    systemProps.produce(new SystemPropertyBuildItem("java.util.logging.manager", 
257
                                                   "org.jboss.logmanager.LogManager"));
258
}
259

260
@BuildStep
261
void addConfigSource(BuildProducer<StaticInitConfigSourceProviderBuildItem> configSources) {
262
    configSources.produce(new StaticInitConfigSourceProviderBuildItem(
263
        "com.example.MyConfigSourceProvider"));
264
}
265

266
@BuildStep
267
void addRuntimeDefaults(BuildProducer<RunTimeConfigurationDefaultBuildItem> defaults) {
268
    defaults.produce(new RunTimeConfigurationDefaultBuildItem("app.timeout", "30s"));
269
    defaults.produce(new RunTimeConfigurationDefaultBuildItem("app.retries", "3"));
270
}
271
```
272

273
## Configuration Definition Types
274

275
### RootDefinition
276

277
Defines a configuration root for type-safe configuration binding.
278

279
```java { .api }
280
class RootDefinition extends GroupDefinition {
281
    /**
282
     * Creates a configuration root definition
283
     */
284
    static RootDefinition builder(String name, Class<?> configClass)
285
        .withDefaults()
286
        .withConverter(Class<? extends Converter<?>> converterClass)
287
        .withValidator(Class<? extends Validator<?>> validatorClass)
288
        .build();
289
    
290
    String getName();
291
    Class<?> getConfigurationClass();
292
}
293
```
294

295
### ClassDefinition and GroupDefinition
296

297
```java { .api }
298
class ClassDefinition {
299
    String getClassName();
300
    Map<String, Object> getDefaults();
301
    List<MethodDefinition> getMethods();
302
    List<FieldDefinition> getFields();
303
}
304

305
class GroupDefinition extends ClassDefinition {
306
    /**
307
     * Nested configuration groups
308
     */
309
    Map<String, GroupDefinition> getGroups();
310
    
311
    /**
312
     * Configuration properties in this group
313
     */
314
    Map<String, PropertyDefinition> getProperties();
315
}
316
```
317

318
**Usage Example:**
319

320
```java
321
// Configuration class
322
@ConfigRoot(phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED)
323
public class DatabaseConfig {
324
    /**
325
     * Database URL
326
     */
327
    @WithDefault("jdbc:h2:mem:test")
328
    public String url;
329
    
330
    /**
331
     * Database driver class
332
     */
333
    @WithDefault("org.h2.Driver")  
334
    public String driver;
335
    
336
    /**
337
     * Connection pool configuration
338
     */
339
    public PoolConfig pool;
340
    
341
    @ConfigGroup
342
    public static class PoolConfig {
343
        @WithDefault("10")
344
        public int maxSize;
345
        
346
        @WithDefault("5")
347
        public int minSize;
348
    }
349
}
350

351
// Build step using configuration
352
@BuildStep
353
void processDatabaseConfig(DatabaseConfig config,
354
                          BuildProducer<DataSourceBuildItem> dataSources) {
355
    dataSources.produce(new DataSourceBuildItem(config.url, config.driver));
356
}
357
```
358

359
## Configuration Mapping
360

361
### ConfigMapping Annotation
362

363
Type-safe configuration binding using interfaces.
364

365
```java { .api }
366
@ConfigMapping(prefix = "app.database")
367
interface DatabaseConfiguration {
368
    
369
    /**
370
     * Database URL with default value
371
     */
372
    @WithDefault("jdbc:h2:mem:test")
373
    String url();
374
    
375
    /**
376
     * Database driver with custom property name
377
     */
378
    @WithName("driver-class")
379
    @WithDefault("org.h2.Driver")
380
    String driverClass();
381
    
382
    /**
383
     * Connection pool configuration group
384
     */
385
    PoolConfiguration pool();
386
    
387
    /**
388
     * Optional SSL configuration
389
     */
390
    Optional<SslConfiguration> ssl();
391
    
392
    interface PoolConfiguration {
393
        @WithDefault("10")
394
        int maxSize();
395
        
396
        @WithDefault("2")
397
        int minSize();
398
        
399
        @WithDefault("30s")
400
        Duration timeout();
401
    }
402
    
403
    interface SslConfiguration {
404
        boolean enabled();
405
        String keystorePath();
406
        String keystorePassword();
407
    }
408
}
409
```
410

411
### ConfigMappingContext
412

413
Context for configuration mapping operations.
414

415
```java { .api }
416
class ConfigMappingContext {
417
    /**
418
     * Registers a configuration mapping interface
419
     */
420
    void registerConfigMapping(Class<?> configMappingClass);
421
    
422
    /**
423
     * Gets registered configuration mappings
424
     */
425
    Set<Class<?>> getConfigMappings();
426
    
427
    /**
428
     * Creates a configuration mapping instance
429
     */
430
    <T> T getConfigMapping(Class<T> mappingClass, Config config);
431
}
432
```
433

434
**Usage Example:**
435

436
```java
437
@BuildStep
438
void registerConfigMapping(BuildProducer<ConfigMappingBuildItem> mappings) {
439
    mappings.produce(new ConfigMappingBuildItem(DatabaseConfiguration.class));
440
}
441

442
@BuildStep  
443
void useConfigMapping(ConfigurationBuildItem configItem,
444
                     BuildProducer<DataSourceBuildItem> dataSources) {
445
    Config config = configItem.getConfig();
446
    DatabaseConfiguration dbConfig = config.getConfigMapping(DatabaseConfiguration.class);
447
    
448
    dataSources.produce(new DataSourceBuildItem(
449
        dbConfig.url(), 
450
        dbConfig.driverClass(),
451
        dbConfig.pool().maxSize()
452
    ));
453
}
454
```
455

456
## Configuration Tracking and Pattern Matching
457

458
### ConfigTrackingWriter
459

460
Tracks configuration changes for hot reloading.
461

462
```java { .api }
463
class ConfigTrackingWriter {
464
    /**
465
     * Writes configuration tracking information
466
     */
467
    static void write(ConfigTrackingConfig config, Path outputPath);
468
    
469
    /**
470
     * Tracks configuration property access
471
     */
472
    static void trackConfigProperty(String propertyName);
473
    
474
    /**
475
     * Gets tracked configuration properties
476
     */
477
    static Set<String> getTrackedProperties();
478
}
479
```
480

481
### ConfigPatternMap
482

483
Maps configuration patterns to values for flexible configuration matching.
484

485
```java { .api }
486
class ConfigPatternMap<T> {
487
    /**
488
     * Creates a new pattern map
489
     */
490
    static <T> Builder<T> builder();
491
    
492
    /**
493
     * Matches a key against registered patterns
494
     */
495
    List<T> findMatches(String key);
496
    
497
    /**
498
     * Gets exact match for a key
499
     */
500
    Optional<T> getExactMatch(String key);
501
    
502
    static class Builder<T> {
503
        Builder<T> put(String pattern, T value);
504
        Builder<T> putAll(Map<String, T> patterns);
505
        ConfigPatternMap<T> build();
506
    }
507
}
508
```
509

510
**Usage Example:**
511

512
```java
513
@BuildStep
514
void configurePatternMatching(ConfigurationBuildItem config,
515
                             BuildProducer<ConfigPatternBuildItem> patterns) {
516
    
517
    ConfigPatternMap<String> datasourcePatterns = ConfigPatternMap.<String>builder()
518
        .put("quarkus.datasource.*.url", "jdbc-url")
519
        .put("quarkus.datasource.*.driver", "driver-class")
520
        .put("quarkus.datasource.*.username", "user")
521
        .put("quarkus.datasource.*.password", "pass")
522
        .build();
523
    
524
    patterns.produce(new ConfigPatternBuildItem("datasource", datasourcePatterns));
525
}
526
```
527

528
## Configuration Validation and Conversion
529

530
### Custom Converters
531

532
```java
533
@BuildStep
534
void registerConverters(BuildProducer<ConfigConverterBuildItem> converters) {
535
    converters.produce(new ConfigConverterBuildItem(DurationConverter.class));
536
    converters.produce(new ConfigConverterBuildItem(SizeConverter.class));
537
}
538

539
public class DurationConverter implements Converter<Duration> {
540
    @Override
541
    public Duration convert(String value) throws IllegalArgumentException {
542
        if (value == null || value.trim().isEmpty()) {
543
            return null;
544
        }
545
        return Duration.parse("PT" + value.toUpperCase());
546
    }
547
}
548
```
549

550
### Configuration Validation
551

552
```java
553
@BuildStep  
554
void validateConfiguration(ConfigurationBuildItem config) {
555
    Config c = config.getConfig();
556
    
557
    // Validate required properties
558
    List<String> requiredProps = Arrays.asList(
559
        "quarkus.application.name",
560
        "quarkus.http.port"
561
    );
562
    
563
    for (String prop : requiredProps) {
564
        if (!c.getOptionalValue(prop, String.class).isPresent()) {
565
            throw new ConfigurationException("Required property " + prop + " is missing");
566
        }
567
    }
568
    
569
    // Validate value ranges
570
    int httpPort = c.getValue("quarkus.http.port", Integer.class);
571
    if (httpPort < 1 || httpPort > 65535) {
572
        throw new ConfigurationException("HTTP port must be between 1 and 65535");
573
    }
574
}
575
```
576

577
## Environment-Specific Configuration
578

579
### Profile-Based Configuration
580

581
```java
582
@BuildStep
583
void setupProfileConfiguration(LaunchModeBuildItem launchMode,
584
                              BuildProducer<SystemPropertyBuildItem> systemProps) {
585
    
586
    String profile = switch (launchMode.getLaunchMode()) {
587
        case DEVELOPMENT -> "dev";
588
        case TEST -> "test";  
589
        case NORMAL -> "prod";
590
    };
591
    
592
    systemProps.produce(new SystemPropertyBuildItem("quarkus.profile", profile));
593
}
594

595
// Configuration with profile-specific values
596
@BuildStep
597
void configureByProfile(ConfigurationBuildItem config,
598
                       LaunchModeBuildItem launchMode,
599
                       BuildProducer<DatabaseBuildItem> database) {
600
    
601
    Config c = config.getConfig();
602
    String profile = c.getOptionalValue("quarkus.profile", String.class).orElse("prod");
603
    
604
    String dbUrl = switch (profile) {
605
        case "dev" -> c.getOptionalValue("quarkus.datasource.dev.jdbc-url", String.class)
606
                       .orElse("jdbc:h2:mem:devdb");
607
        case "test" -> c.getOptionalValue("quarkus.datasource.test.jdbc-url", String.class)
608
                        .orElse("jdbc:h2:mem:testdb");
609
        default -> c.getValue("quarkus.datasource.jdbc-url", String.class);
610
    };
611
    
612
    database.produce(new DatabaseBuildItem(dbUrl));
613
}
614
```
615

616
## Configuration Build Steps
617

618
### Common Configuration Patterns
619

620
```java
621
@BuildSteps
622
public class ConfigurationProcessor {
623
    
624
    @BuildStep
625
    ConfigurationBuildItem readConfiguration(ApplicationArchivesBuildItem archives,
626
                                           LaunchModeBuildItem launchMode) {
627
        // Read and process configuration from all sources
628
    }
629
    
630
    @BuildStep
631
    void processSystemProperties(ConfigurationBuildItem config,
632
                                BuildProducer<SystemPropertyBuildItem> systemProps) {
633
        // Convert config properties to system properties where needed
634
    }
635
    
636
    @BuildStep
637
    @Record(ExecutionTime.STATIC_INIT)
638
    void setupStaticConfig(ConfigRecorder recorder,
639
                          List<StaticInitConfigSourceProviderBuildItem> configSources) {
640
        List<String> providers = configSources.stream()
641
            .map(StaticInitConfigSourceProviderBuildItem::getConfigSourceProviderClassName)
642
            .collect(Collectors.toList());
643
        recorder.registerStaticConfigSources(providers);
644
    }
645
    
646
    @BuildStep
647
    @Record(ExecutionTime.RUNTIME_INIT)
648
    void setupRuntimeConfig(ConfigRecorder recorder,
649
                           List<RunTimeConfigurationDefaultBuildItem> defaults,
650
                           ShutdownContextBuildItem shutdown) {
651
        Map<String, String> defaultValues = defaults.stream()
652
            .collect(Collectors.toMap(
653
                RunTimeConfigurationDefaultBuildItem::getKey,
654
                RunTimeConfigurationDefaultBuildItem::getValue
655
            ));
656
        recorder.setupRuntimeConfig(defaultValues, shutdown);
657
    }
658
}
659
```