JAVA-260 · Lesson 6 of 12 · 23 min

Configuration and profiles

▶ Video coming soon A video version of this lesson is on the way.

On Wednesday, February 16, the last session before reading week, Leif sat in. He ran the shop's small server, the one that would run the booking service, and he had found the database password in Hamza's application.yml, pushed to the secondgear repository the week before. "It is in the history now," he said, "so the password has to change, and from today it lives on the server, not in Git." This lesson is about externalized configuration: keeping settings out of the code, choosing them per environment with profiles, binding them to typed records and keeping secrets where they belong.

One build, many environments

The same JAR has to run in three places: on Hamza's laptop with a local database and the log-only notifier, in the test suite with a throwaway database, and on Leif's server with the real database and the real text-message provider. Rebuilding the JAR for each would mean the thing tested is not the thing deployed. Instead, the code reads properties, named settings such as spring.datasource.url or shop.booking.slots-per-hour, and each environment supplies its own values. Spring Boot collects them from many property sources and combines them in a fixed order, so that a value set closer to the running environment overrides one set further away.

Some of the property sources Spring Boot reads, from lowest to highest precedence (simplified).
Source (later wins)ExampleTypical use
Defaults in code@ConfigurationProperties record defaultsSafe fallbacks
application.yml in the JARshop.booking.slots-per-hour: 2Settings shared by all environments
application-{profile}.yml in the JARapplication-dev.ymlPer-environment settings that are not secret
A config file outside the JAR/etc/secondgear/application.yml on the serverServer-specific settings
Operating system environment variablesSTOCKSTORE_DB_PASSWORDSecrets and container settings
Java system properties-Dshop.booking.slots-per-hour=3One-off overrides
Command-line arguments--server.port=8081One-off overrides
Test properties@SpringBootTest(properties = ...)Values for one test

Merging property sources

The rule "later sources win, key by key" is easy to state and worth seeing. The example loads three sources into java.util.Properties maps: the packaged defaults, a profile file and the environment. It merges them in order, and for each key it records which source supplied the winning value. That record is what Spring Boot's /actuator/env endpoint shows, and it is the first thing to look at when a setting is not the value you expected.

Java Example · Main.java
import java.util.*;

public class Main {
    record Source(String name, Properties props) {}

    static Properties props(String... kv) {
        Properties p = new Properties();
        for (int i = 0; i < kv.length; i += 2) p.setProperty(kv[i], kv[i + 1]);
        return p;
    }

    public static void main(String[] args) {
        List<Source> sources = List.of(
                new Source("application.yml", props(
                        "server.port", "8080",
                        "shop.booking.slots-per-hour", "2",
                        "shop.notifier", "log",
                        "spring.datasource.url", "jdbc:postgresql://localhost:5432/stockstore")),
                new Source("application-prod.yml", props(
                        "shop.notifier", "sms",
                        "spring.datasource.url", "jdbc:postgresql://db.internal:5432/stockstore")),
                new Source("environment", props(
                        "spring.datasource.password", "(from STOCKSTORE_DB_PASSWORD)",
                        "server.port", "8443")));

        Map<String, String> value = new TreeMap<>(), from = new HashMap<>();
        for (Source s : sources) {
            for (String key : s.props().stringPropertyNames()) {
                value.put(key, s.props().getProperty(key));
                from.put(key, s.name());
            }
        }
        value.forEach((k, v) -> System.out.printf("%-30s %-46s <- %s%n", k, v, from.get(k)));
    }
}
Output
server.port                    8443                                           <- environment
shop.booking.slots-per-hour    2                                              <- application.yml
shop.notifier                  sms                                            <- application-prod.yml
spring.datasource.password     (from STOCKSTORE_DB_PASSWORD)                  <- environment
spring.datasource.url          jdbc:postgresql://db.internal:5432/stockstore  <- application-prod.yml

What this code does

Each source is a Properties map, and the merge visits them from lowest to highest precedence, so a later source simply overwrites the earlier value for the same key. Keys set only once, such as the slots per hour, keep their packaged default. The TreeMap sorts the result by key, and the last column names the source that won, much like the Actuator env endpoint.

In this course's examples the password's value is never printed. The same rule applies to real logs and to Actuator, which by default shows the names of properties but masks their values.

Profiles

A profile is a named group of settings and beans that is switched on for one environment. Setting spring.profiles.active=prod, usually through the SPRING_PROFILES_ACTIVE environment variable on the server, makes Spring Boot load application-prod.yml on top of application.yml and create any bean marked @Profile("prod"). Beans marked for another profile do not exist at all. That is the cleanest answer to the two-notifier problem from lesson 2: the SMS notifier is a prod bean and the log notifier a dev bean, so exactly one exists wherever the application runs.

application.yml
# application.yml: shared by every environment
shop:
  booking:
    slots-per-hour: 2
    first-start: "09:00"
    last-start: "15:00"
    open-days: [TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY]
  notifier: log
spring:
  application:
    name: booking-api
---
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:postgresql://localhost:5432/stockstore
    username: hamza
    password: ${DEV_DB_PASSWORD:dev-only}
---
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: jdbc:postgresql://db.internal:5432/stockstore
    username: booking_app
    password: ${STOCKSTORE_DB_PASSWORD}
shop:
  notifier: sms

What this code does

The three dashes split one YAML file into documents, and spring.config.activate.on-profile makes a document apply only when that profile is active. The prod password has no default after the placeholder, so the application refuses to start if the environment variable is missing. The dev document's placeholder has a fallback after the colon, which is acceptable only because that database exists on Hamza's laptop alone.

Java Example · NotifierConfig.java (needs Spring)
@Configuration
class NotifierConfig {
    @Bean
    @Profile("prod")
    Notifier smsNotifier(SmsProperties sms, RestClient.Builder http) {
        return new SmsNotifier(sms, http.build());
    }

    @Bean
    @Profile("!prod")
    Notifier logNotifier() {
        return new LogNotifier();
    }
}

What this code does

Only one of the two @Bean methods runs in any environment: smsNotifier when prod is active, and logNotifier in every other case, including tests. The exclamation mark negates a profile. No constructor needs a qualifier, because only one Notifier bean ever exists.

Keep profiles few and named for environments, such as dev, test and prod. A profile per feature, such as with-sms or fast-start, multiplies the combinations that nobody has tested. For an optional feature, a property with @ConditionalOnProperty is clearer.

Relaxed binding and environment variables

Environment variable names cannot contain dots or dashes on most systems, so Spring Boot uses relaxed binding: the property shop.booking.slots-per-hour can be set by the environment variable SHOP_BOOKING_SLOTSPERHOUR. The rule for environment variables is to replace dots with underscores, remove dashes and use upper case. In YAML and properties files the canonical form is lower case with dashes, the kebab case used throughout this course. The example converts in both directions and shows which variable Leif must set for each setting.

Java Example · Main.java
import java.util.*;

public class Main {
    static String toEnvVar(String property) {
        return property.replace("-", "").replace(".", "_").replace("[", "_").replace("]", "").toUpperCase();
    }

    static Optional<String> lookup(Map<String, String> env, String property) {
        return Optional.ofNullable(env.get(toEnvVar(property)));
    }

    public static void main(String[] args) {
        for (String p : List.of("spring.datasource.password", "shop.booking.slots-per-hour",
                "spring.profiles.active", "shop.booking.open-days[0]")) {
            System.out.printf("%-30s -> %s%n", p, toEnvVar(p));
        }
        Map<String, String> env = Map.of("SPRING_PROFILES_ACTIVE", "prod", "SHOP_BOOKING_SLOTSPERHOUR", "3");
        System.out.println("slots per hour = " + lookup(env, "shop.booking.slots-per-hour").orElse("(default 2)"));
        System.out.println("first start    = " + lookup(env, "shop.booking.first-start").orElse("(default 09:00)"));
    }
}
Output
spring.datasource.password     -> SPRING_DATASOURCE_PASSWORD
shop.booking.slots-per-hour    -> SHOP_BOOKING_SLOTSPERHOUR
spring.profiles.active         -> SPRING_PROFILES_ACTIVE
shop.booking.open-days[0]      -> SHOP_BOOKING_OPENDAYS_0
slots per hour = 3
first start    = (default 09:00)

What this code does

toEnvVar applies Spring Boot's documented rule for environment variables: dashes go, dots and list brackets become underscores and everything is upper case. lookup then finds the property in a map that stands in for the real environment, which keeps the output the same on every machine. The slots per hour come from the environment, and the first start time falls back to its default because no variable sets it.

Typed settings with @ConfigurationProperties

Reading properties one at a time with @Value and a placeholder string works, but it scatters setting names across the code and checks nothing. A @ConfigurationProperties record binds a whole prefix to typed components at start-up, converting text to numbers, times, lists and enums, and with @Validated it applies Bean Validation constraints too, so a nonsense value stops the application before it serves a single request.

Java Example · BookingProperties.java (needs Spring Boot)
package org.secondgear.api.config;

import jakarta.validation.constraints.*;
import java.time.*;
import java.util.Set;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.validation.annotation.Validated;

@Validated
@ConfigurationProperties("shop.booking")
public record BookingProperties(
        @DefaultValue("2") @Min(1) @Max(4) int slotsPerHour,
        @DefaultValue("09:00") LocalTime firstStart,
        @DefaultValue("15:00") LocalTime lastStart,
        @NotEmpty Set<DayOfWeek> openDays,
        @DefaultValue("America/Toronto") ZoneId zone) {
}

What this code does

Every component maps to a property under shop.booking, with the dashes of slots-per-hour matched to the camel case slotsPerHour. Spring converts the text in the YAML to LocalTime, DayOfWeek and ZoneId values, and @DefaultValue supplies a value when none is set. With @Validated, setting slots-per-hour to 0 makes start-up fail with a message naming the property.

The record is registered with @ConfigurationPropertiesScan on the application class, and any bean can then receive BookingProperties through its constructor, like any other dependency. The next example does the binding by hand from a Properties map, including the conversions and the range check, to show what Spring does at start-up.

Java Example · Main.java
import java.time.*;
import java.util.*;

public class Main {
    record BookingProperties(int slotsPerHour, LocalTime firstStart, LocalTime lastStart, Set<DayOfWeek> openDays) {
        BookingProperties {
            if (slotsPerHour < 1 || slotsPerHour > 4)
                throw new IllegalArgumentException("shop.booking.slots-per-hour must be between 1 and 4, but was " + slotsPerHour);
            if (!lastStart.isAfter(firstStart))
                throw new IllegalArgumentException("shop.booking.last-start must be after first-start");
        }
    }

    static BookingProperties bind(Properties p) {
        String days = p.getProperty("shop.booking.open-days", "TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY");
        Set<DayOfWeek> open = EnumSet.noneOf(DayOfWeek.class);
        for (String d : days.split(",")) open.add(DayOfWeek.valueOf(d.trim().toUpperCase()));
        return new BookingProperties(
                Integer.parseInt(p.getProperty("shop.booking.slots-per-hour", "2")),
                LocalTime.parse(p.getProperty("shop.booking.first-start", "09:00")),
                LocalTime.parse(p.getProperty("shop.booking.last-start", "15:00")),
                open);
    }

    public static void main(String[] args) {
        Properties defaults = new Properties();
        System.out.println(bind(defaults));

        Properties summer = new Properties();
        summer.setProperty("shop.booking.open-days", "monday, tuesday, wednesday, thursday, friday, saturday");
        summer.setProperty("shop.booking.last-start", "16:00");
        System.out.println(bind(summer).openDays().size() + " open days, last start " + bind(summer).lastStart());

        Properties typo = new Properties();
        typo.setProperty("shop.booking.slots-per-hour", "20");
        try {
            bind(typo);
        } catch (IllegalArgumentException e) {
            System.out.println("Start-up fails: " + e.getMessage());
        }
    }
}
Output
BookingProperties[slotsPerHour=2, firstStart=09:00, lastStart=15:00, openDays=[TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY]]
6 open days, last start 16:00
Start-up fails: shop.booking.slots-per-hour must be between 1 and 4, but was 20

What this code does

bind reads each key with a default, converts the text into an int, two LocalTime values and an EnumSet of days, and builds the record. The compact constructor checks the ranges, standing in for @Min, @Max and a cross-field rule, so a typo of 20 for 2 stops the program with a message naming the property. The summer settings show that case and spacing in the list of days do not matter, as with Spring's relaxed conversion of enums.

Five horizontal layers stacked like sheets of paper, from bottom to top: application.yml, application-prod.yml, an external config file, environment variables, command-line arguments. A vertical arrow on the right points up and is marked higher precedence. On the left, the key shop.notifier shows log on the bottom layer and sms on the profile layer, and the final value sms is circled at the top.
Property sources stacked by precedence; each key takes its value from the highest layer that sets it.

Secrets

A secret is any value that grants access: database passwords, API keys for the text-message provider, signing keys. Secrets never go in source code, in application.yml in the repository, in the JAR, in logs or in error messages. A secret pushed to Git must be treated as leaked even if the commit is removed, because clones, forks and backups keep it, so the only fix is to rotate it: issue a new value and revoke the old. That is what Leif did on February 16.

Where secrets may and may not live.
WhereSecrets?Why
Java source and application.yml in GitNeverEveryone with repository access, and every clone, has them forever
Environment variables on the serverYesSet by the person who runs the server; not in the build
A secrets file readable only by the service userYesFor example /etc/secondgear/booking.env with mode 600
A secrets manager or vaultYes, for larger setupsCentral rotation and audit
Logs, error responses, Actuator outputNeverSpring Boot masks values in Actuator by default; keep it that way

Two habits stop most leaks. First, a .gitignore entry for local files such as .env and application-local.yml, so a developer's own values cannot be committed by accident. Second, a secret scanner in the pull-request checks, which Leif added to the secondgear build that week, so a password-shaped string in a diff fails the build before review.

# On the shop's server, in the service's environment file (not in Git)
SPRING_PROFILES_ACTIVE=prod
STOCKSTORE_DB_PASSWORD=<set by Leif, rotated 2028-02-16>
SMS_API_KEY=<set by Leif>

# Starting by hand for a check
java -jar booking-api.jar --debug

What this code does

The environment file is read by the service manager when it starts the application, so the values exist only in the running process's environment. The angle-bracket placeholders stand for values that are never written into any document. The --debug flag prints the condition evaluation report, which also lists the active profiles.

Representative failure
SPRING_PROFILES_ACTIVE=prod java -jar booking-api.jar
Output
APPLICATION FAILED TO START

Description:
Could not resolve placeholder 'STOCKSTORE_DB_PASSWORD' in value "${STOCKSTORE_DB_PASSWORD}"

Action:
Set the STOCKSTORE_DB_PASSWORD environment variable or define the property in an external configuration source.

What this code does

Without STOCKSTORE_DB_PASSWORD the placeholder cannot be resolved. The application stops at start-up instead of trying to connect with an empty password.

Try it yourself

Resolve placeholders

Complete resolve so that it replaces each placeholder in a value, written as a dollar sign and braces around NAME or NAME:default, with the entry for NAME in env, or with the default when NAME is missing.

If NAME is missing and there is no default, throw an IllegalStateException with the message Could not resolve placeholder 'NAME'; main prints it.

import java.util.*;
import java.util.regex.*;

public class Main {
    static String resolve(String value, Map<String, String> env) {
        return value;
    }

    public static void main(String[] args) {
        Map<String, String> env = Map.of("DB_HOST", "db.internal", "DB_NAME", "stockstore");
        System.out.println(resolve("jdbc:postgresql://${DB_HOST}:${DB_PORT:5432}/${DB_NAME}", env));
        System.out.println(resolve("${SMS_SENDER:Second Gear}", env));
        try {
            System.out.println(resolve("${STOCKSTORE_DB_PASSWORD}", env));
        } catch (IllegalStateException e) {
            System.out.println(e.getMessage());
        }
    }
}

Try it yourself

Activate a profile

Complete effective so that it starts from base, then applies the overrides of each profile in active, in order, and returns the merged map.

Profiles that do not exist in profiles are ignored.

import java.util.*;

public class Main {
    static Map<String, String> effective(Map<String, String> base, Map<String, Map<String, String>> profiles, List<String> active) {
        return new TreeMap<>(base);
    }

    public static void main(String[] args) {
        Map<String, String> base = Map.of("shop.notifier", "log", "server.port", "8080", "shop.booking.slots-per-hour", "2");
        Map<String, Map<String, String>> profiles = Map.of(
                "prod", Map.of("shop.notifier", "sms"),
                "summer", Map.of("shop.booking.slots-per-hour", "3"));
        System.out.println(effective(base, profiles, List.of()));
        System.out.println(effective(base, profiles, List.of("prod")));
        System.out.println(effective(base, profiles, List.of("prod", "summer", "staging")));
    }
}

Leif rotated the database password that evening and wrote the new one only into the server's environment file. Hamza added application-local.yml and .env to .gitignore and opened a pull request for the secret scanner. Then reading week began.

Common mistakes

  • MistakeCommitting a password and deleting it in the next commit.

    InsteadTreat any secret that reached Git as leaked and rotate it.

  • MistakeBuilding a different JAR for each environment.

    InsteadBuild once and supply per-environment values through profiles and property sources.

  • MistakeReading settings with @Value strings all over the code.

    InsteadBind a prefix to a validated @ConfigurationProperties record and inject it.

  • MistakeCreating a profile for every feature.

    InsteadKeep profiles for environments and use @ConditionalOnProperty for optional features.

  • MistakeGiving a production secret a default value in the placeholder.

    InsteadLeave production secrets without defaults so a missing value stops start-up.

Summary and key terms

  • Externalized configuration lets one JAR run in every environment.
  • Spring Boot reads properties from many sources in a fixed order, and later sources such as environment variables and command-line arguments override earlier ones key by key.
  • Profiles, activated with spring.profiles.active, add application-{profile}.yml or profile documents and switch on @Profile beans, so exactly one implementation exists per environment.
  • Relaxed binding maps environment variables such as SHOP_BOOKING_SLOTSPERHOUR to kebab-case properties. @ConfigurationProperties records bind a prefix to typed, validated components at start-up.
  • Placeholders that name STOCKSTORE_DB_PASSWORD pull secrets from the environment; secrets never go in Git, logs or responses, and a leaked one is rotated.
Externalized configuration
Settings supplied from outside the code, so one build can run anywhere.
Property source
A place properties come from, such as a YAML file or the environment.
Profile
A named set of settings and beans activated for one environment.
spring.profiles.active
The property that chooses which profiles are active.
Relaxed binding
Matching property names written in different styles, such as kebab case and environment-variable form.
@ConfigurationProperties
Binds all properties under a prefix to a typed class or record.
Placeholder
A dollar-brace reference to another property or environment variable, optionally with a default.
Secret
A value that grants access, such as a password or API key.
Rotation
Replacing a secret with a new value and revoking the old one.
Kebab case
Lower-case words joined by dashes, such as slots-per-hour.

Practice problems

Work each problem on paper first, then reveal the answer to check.

  1. Which wins: a value in application.yml or the same key in an environment variable?

    Show answer

    The environment variable.

  2. What environment variable sets shop.booking.slots-per-hour?

    Show answer

    SHOP_BOOKING_SLOTSPERHOUR.

  3. How do you make a bean exist only in production?

    Show answer

    Mark its class or @Bean method with @Profile("prod").

  4. Why leave the production password placeholder without a default?

    Show answer

    So that start-up fails if the variable is missing.

  5. A password reached the Git history. What must happen?

    Show answer

    Rotate it: issue a new password and revoke the old one.

Lesson quiz · 5 questions

Score 60% or more to complete this lesson.

Take the quiz