Environment variables in configuration in Spring Boot - Deep Dive

Overview - Environment variables in configuration

What is it?

Environment variables in configuration are values set outside your Spring Boot application that your app can read and use to adjust its behavior. They let you change settings like database URLs or API keys without changing the code. This makes your app flexible and easier to manage across different environments like development, testing, and production.

Why it matters

Without environment variables, you would have to hard-code sensitive or environment-specific data inside your app, which is risky and inflexible. If you want to change a setting, you’d need to rebuild or redeploy your app. Environment variables solve this by letting you change configuration quickly and safely, improving security and making your app adaptable to different situations.

Where it fits

Before learning environment variables, you should understand basic Spring Boot configuration using application.properties or application.yml files. After this, you can learn about profiles and externalized configuration to manage multiple environments effectively.

Mental Model

Core Idea

Environment variables are external settings that your Spring Boot app reads at startup to customize its behavior without changing code.

Think of it like...

It's like setting the thermostat in your house: you don't rebuild the heater to change the temperature; you just adjust the thermostat setting from outside.

┌───────────────────────────────┐
│ Environment Variables (OS)    │
│ ┌───────────────────────────┐ │
│ │ DB_URL=jdbc:mysql://...   │ │
│ │ API_KEY=abcdef12345       │ │
│ └───────────────────────────┘ │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ Spring Boot Application        │
│ Reads env vars at startup      │
│ Applies settings dynamically  │
└───────────────────────────────┘

Build-Up - 8 Steps

1

Foundation

What Are Environment Variables

Concept: Introduce environment variables as external key-value pairs set outside the app.

Environment variables are like labels with values stored by your operating system or container. They hold information your app can use, such as usernames, passwords, or URLs. You set them once, and any app running on that system can read them.

Result

You understand that environment variables exist outside your app and can be accessed by it.

Understanding that environment variables live outside your app helps you see how they keep sensitive data separate from code.

2

Foundation

Spring Boot Configuration Basics

Concept: Explain how Spring Boot uses application.properties or application.yml for configuration.

Spring Boot reads configuration from files like application.properties or application.yml inside your project. These files contain key-value pairs that tell your app how to behave, like server ports or database connections.

Result

You know where Spring Boot normally gets its settings and how to change them.

Knowing the default config files sets the stage for understanding how environment variables can override or complement these settings.

3

Intermediate

Using Environment Variables in Spring Boot

🤔Before reading on: do you think Spring Boot reads environment variables automatically or do you need extra code? Commit to your answer.

Concept: Show how Spring Boot automatically reads environment variables and maps them to configuration properties.

Spring Boot automatically checks environment variables and matches them to properties by converting names. For example, an env var named SPRING_DATASOURCE_URL will override spring.datasource.url in your config file. You don't need extra code; Spring Boot does this for you.

Result

Your app uses environment variables to override config values without code changes.

Understanding automatic mapping means you can safely use environment variables without extra wiring, making configuration flexible and clean.

4

Intermediate

Naming Conventions for Environment Variables

🤔Before reading on: do you think environment variable names match property names exactly or are transformed? Commit to your answer.

Concept: Explain how Spring Boot transforms property names to environment variable names using uppercase and underscores.

Spring Boot converts property names by replacing dots with underscores and making letters uppercase. For example, spring.datasource.username becomes SPRING_DATASOURCE_USERNAME. This naming style is standard for environment variables in most operating systems.

Result

You can correctly name environment variables to override any Spring Boot property.

Knowing the naming rules prevents confusion and errors when setting environment variables to control your app.

5

Intermediate

Priority Order of Configuration Sources

🤔Before reading on: do you think environment variables have higher or lower priority than application.properties? Commit to your answer.

Concept: Teach the order Spring Boot uses to decide which configuration value to apply when multiple sources exist.

Spring Boot uses a priority order: environment variables override application.properties, which override default values. This means if an environment variable and a property file both set the same key, the environment variable wins.

Result

You understand how Spring Boot chooses configuration values when multiple sources exist.

Knowing priority helps you predict which setting your app will use, avoiding surprises in different environments.

6

Advanced

Using Profiles with Environment Variables

🤔Before reading on: do you think environment variables can be profile-specific or only global? Commit to your answer.

Concept: Show how environment variables can work with Spring profiles to customize config per environment.

Spring profiles let you group settings for different environments like dev or prod. You can set environment variables that activate a profile or override profile-specific properties. For example, SPRING_PROFILES_ACTIVE=prod activates the prod profile, and environment variables can override prod-specific settings.

Result

You can manage multiple environments flexibly using profiles and environment variables together.

Combining profiles with environment variables gives powerful control over app behavior across environments without code changes.

7

Advanced

Security Best Practices for Environment Variables

Concept: Discuss how environment variables help keep secrets safe and what to watch out for.

Storing sensitive data like passwords in environment variables keeps them out of code and config files, reducing risk. However, environment variables can be exposed in logs or process lists if not handled carefully. Use secure deployment tools and limit access to environment variables.

Result

You know how to use environment variables securely to protect sensitive information.

Understanding security risks ensures you use environment variables safely, protecting your app and users.

8

Expert

Dynamic Refresh of Environment Variables at Runtime

🤔Before reading on: do you think Spring Boot can update environment variables while running or only at startup? Commit to your answer.

Concept: Explain how Spring Boot can refresh configuration from environment variables dynamically using Spring Cloud features.

By default, Spring Boot reads environment variables only at startup. But with Spring Cloud Config and actuator endpoints, you can refresh configuration at runtime without restarting. This allows your app to adapt to changes in environment variables dynamically, useful in cloud or container setups.

Result

Your app can update configuration on the fly, improving uptime and flexibility.

Knowing about dynamic refresh helps build resilient apps that adapt to changing environments without downtime.

Under the Hood

Spring Boot uses a ConfigurableEnvironment interface that aggregates multiple property sources, including environment variables. At startup, it reads environment variables from the operating system and maps them to property keys by converting names. These values are stored in a high-priority property source, so they override lower-priority sources like application.properties. When your app requests a configuration value, Spring Boot checks these sources in order and returns the first match.

Why designed this way?

This design allows flexible configuration from many sources without code changes. Environment variables are external and secure, so giving them high priority lets users override defaults easily. The naming conversion follows OS conventions for compatibility. Alternatives like hardcoding or config files alone were less flexible and risked exposing secrets.

┌───────────────────────────────┐
│ Operating System Environment   │
│ Variables (SPRING_DATASOURCE) │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ Spring Boot ConfigurableEnv    │
│ ┌───────────────────────────┐ │
│ │ PropertySource: Env Vars  │ │
│ │ (High Priority)           │ │
│ ├───────────────────────────┤ │
│ │ PropertySource: Files     │ │
│ │ (application.properties)  │ │
│ └───────────────────────────┘ │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ Application Beans Read Config  │
│ Values from ConfigurableEnv    │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do environment variables set inside your app code affect the OS environment? Commit yes or no.

Common Belief: Setting environment variables inside your Spring Boot code changes the OS environment variables.

Reality: Environment variables set inside the app only affect the app's process and do not change the OS environment variables globally.

Why it matters: Assuming your app can change OS environment variables leads to confusion when other processes don't see those changes.

Quick: Do you think environment variables can contain dots (.) like property names? Commit yes or no.

Common Belief: Environment variables can have dots in their names to match property keys exactly.

Reality: Most operating systems do not support dots in environment variable names; Spring Boot converts dots to underscores for mapping.

Why it matters: Using dots in env var names causes them to be ignored or misread, breaking configuration overrides.

Quick: Do environment variables always override application.properties regardless of how you run the app? Commit yes or no.

Common Belief: Environment variables always have the highest priority and override any config file.

Reality: If you explicitly set properties via command-line arguments, those have higher priority than environment variables.

Why it matters: Misunderstanding priority order can cause unexpected config values and bugs in different deployment setups.

Quick: Can environment variables be used to change configuration after the app has started without restarting? Commit yes or no.

Common Belief: You can change environment variables anytime and the running Spring Boot app will pick up changes automatically.

Reality: By default, Spring Boot reads environment variables only at startup; runtime changes require special setup like Spring Cloud Config.

Why it matters: Expecting dynamic updates without proper setup leads to confusion and wasted debugging time.

Expert Zone

1

Environment variables are case-sensitive on some OSes but not on others, which can cause subtle bugs in cross-platform deployments.

2

Spring Boot supports relaxed binding, so environment variables can match properties ignoring case and separators, but this can sometimes cause unexpected matches.

3

When running in containers, environment variables are often injected at container start, so understanding container lifecycle is key to managing config effectively.

When NOT to use

Environment variables are not ideal for very large or complex configurations; in such cases, external config servers or vaults are better. Also, for secrets management, dedicated secret stores provide better security than plain environment variables.

Production Patterns

In production, environment variables are often managed by orchestration tools like Kubernetes or Docker Compose, injected securely at runtime. They are combined with Spring profiles to switch between dev, test, and prod settings seamlessly.

Connections

12-Factor App Methodology

Environment variables are a core principle in 12-factor apps for config management.

Understanding environment variables in Spring Boot helps implement 12-factor apps, making your software portable and scalable.

Operating System Process Environment

Environment variables originate from the OS process environment that Spring Boot reads at startup.

Knowing how OS process environments work clarifies why environment variables behave differently across platforms and shells.

Secrets Management in Cybersecurity

Environment variables are one method to manage secrets securely in applications.

Learning environment variables' role in secrets management connects software config to broader cybersecurity practices.

Common Pitfalls

#1 Using dots in environment variable names causing them to be ignored.

Wrong approach:

export spring.datasource.url=jdbc:mysql://localhost:3306/db

Correct approach:

export SPRING_DATASOURCE_URL=jdbc:mysql://localhost:3306/db

Root cause:

Misunderstanding that environment variables cannot contain dots and must use underscores instead.

#2 Expecting environment variable changes to apply without restarting the app.

Wrong approach:

Change environment variable in OS and expect running Spring Boot app to pick it up immediately.

Correct approach:

Restart the Spring Boot app or use Spring Cloud Config with refresh endpoints to apply changes at runtime.

Root cause:

Not knowing that Spring Boot reads environment variables only once at startup by default.

#3 Setting environment variables inside the app code to affect global OS environment.

Wrong approach:

System.getenv().put("MY_VAR", "value"); // expecting global change

Correct approach:

// Set environment variables outside the app, e.g., in shell or container config

Root cause:

Confusing process-level environment with global OS environment variables.

Key Takeaways

Environment variables let you configure Spring Boot apps externally without changing code.

Spring Boot automatically maps environment variables to properties using uppercase and underscores.

Environment variables have higher priority than config files but lower than command-line args.

They help keep sensitive data out of code but require careful handling for security.

By default, environment variables are read only at startup; dynamic refresh needs extra setup.