Externalized configuration, precedence and profiles

Spring Boot reads configuration from many property sources — config files, environment variables, JVM system properties, command-line arguments and more — and merges them into one Environment. When the same key appears in several, the source with the higher precedence wins. A trimmed version of the documented order, highest first:

1. command-line arguments (--server.port=9000)
2. Java system properties (-Dserver.port=9000)
3. OS environment variables (SERVER_PORT=9000)
4. profile-specific config files (application-prod.properties)
5. application.properties / application.yml

Within the config files, a file outside the packaged jar beats the one inside it — even a profile file: an application.properties next to the jar overrides an application-prod.properties packaged inside it. The practical consequence is the deployment model Boot is built for: ship one artifact with sensible defaults in application.properties, and let each environment override what it needs with environment variables or arguments.

Environment variable names

Most platforms do not allow dots or dashes in environment variable names, so Boot's relaxed binding maps them: replace . with _, drop -, and uppercase. spring.datasource.url is SPRING_DATASOURCE_URL; app.max-retries is APP_MAXRETRIES.

1import java.util.*;2 3public class Solution {4    static String envName(String key) {5        return key.replace(".", "_").replace("-", "").toUpperCase();6    }7 8    static String resolve(String key, Map<String, String> args, Map<String, String> env,9                          Map<String, String> profileFile, Map<String, String> baseFile) {10        if (args.containsKey(key)) return args.get(key) + " (command line)";11        if (env.containsKey(envName(key))) return env.get(envName(key)) + " (env " + envName(key) + ")";12        if (profileFile.containsKey(key)) return profileFile.get(key) + " (application-prod)";13        if (baseFile.containsKey(key)) return baseFile.get(key) + " (application)";14        return "<unset>";15    }16 17    public static List<String> run() {18        Map<String, String> base = Map.of(19            "server.port", "8080",20            "app.max-retries", "3",21            "app.greeting", "hello",22            "logging.level.root", "INFO");23        Map<String, String> prod = Map.of("server.port", "8443", "logging.level.root", "WARN");24        Map<String, String> env = Map.of("APP_MAXRETRIES", "5", "SERVER_PORT", "9090");25        Map<String, String> args = Map.of("logging.level.root", "DEBUG");26 27        List<String> out = new ArrayList<>();28        for (String key : List.of("server.port", "app.max-retries", "app.greeting", "logging.level.root", "app.timeout")) {29            out.add(key + " = " + resolve(key, args, env, prod, base));30        }31        return out;32    }33}

Reading configuration: prefer typed properties

@ConfigurationProperties(prefix = "app.payments")
@Validated
public record PaymentProperties(
        @NotBlank String provider,
        Duration timeout,
        int maxRetries) {}

Registered with @EnableConfigurationProperties(PaymentProperties.class) or @ConfigurationPropertiesScan, this binds app.payments.provider, app.payments.timeout=5s (converted to a Duration) and app.payments.max-retries in one place, validated at startup. A Duration accepts a number with a unit (500ms, 30s, 2m, 1h, 1d); a bare number is read as milliseconds unless the field carries @DurationUnit, so timeout=5 means five milliseconds, not seconds. @Value("${app.payments.timeout:5s}") reads a single value with an optional default after the colon; it is fine for one-off values but scatters the configuration of a feature across many classes.

Profiles

A profile is a named slice of configuration. Activate profiles with spring.profiles.active=prod,eu (or ). Two things then change: