Spring Boot: how to manage configuration for different environments

If you’ve ever worked with Spring Boot applications across multiple environments — such as development, staging, and production — you know how challenging it can be to keep configurations organized, secure, and consistent. Each environment often requires different variables: database URLs, credentials, caching parameters, API keys, and more.

Managing these differences efficiently is essential to avoid critical errors, prevent sensitive data leaks, and ensure application stability in production.

In this article, I’ll walk you through the main strategies for managing configurations in Spring Boot projects, including:

• Using application-{profile}.properties files and active profiles;
• How to externalize configurations with environment variables;
• Secure alternatives for managing secrets (like Spring Cloud Config and Vault);
• Best practices for versioning and deployment.

The Problem: Configuration Chaos Across Environments

Hardcoding these values or using a single configuration file leads to brittle applications. There is a risk of deploying production settings in development or, worse, exposing secrets in version control.

To solve this, Spring Boot provides a powerful mechanism for environment-specific configuration through profiles.

Profiles in Spring Boot

Spring Boot allows you to define multiple application.properties (or application.yaml) files. One for each environment. Each file contains environment-specific settings like database URLs, credentials, logging levels, and feature flags. Then, you can activate the appropriate profile using the spring.profiles.active property.

src/
└── main/
    └── resources/
        ├── application.yml
        ├── application-dev.yml
        ├── application-staging.yml
        └── application-prod.yml

In the base application.yaml file you can define the default environment:

spring:
  profiles:
    active: dev  # <- defines default profile (can be subscribed via CLI/env)

  datasource:
    driver-class-name: org.postgresql.Driver
    username: ${DB_USER} # environment var
    password: ${DB_PASS} # environment var

And then you can set the variable values for each environment:

application-dev.yaml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/dev_db
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
    properties:
      hibernate:
        format_sql: true

server:
  port: 8080
logging:
  level:
    root: DEBUG

application-prod.yaml:

spring:
  datasource:
    url: jdbc:postgresql://prod-db.internal.company:5432/prod_db
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false

server:
  port: 8080
logging:
  level:
    root: INFO

How to activate the correct profile

If you leave spring.profiles.activate=dev in application.yml, it will automatically use application-dev.yml. For other environments we must activate the profile explicitly using the command line or environment variables. For example:

java -jar app.jar --spring.profiles.active=prod

You can also set the SPRING_PROFILES_ACTIVE environment variable:

export SPRING_PROFILES_ACTIVE=prod

Configuring SPRING_PROFILES_ACTIVE in Docker

You can set the SPRING_PROFILES_ACTIVE value in the Dockerfile:

FROM eclipse-temurin:17-jdk-alpine

WORKDIR /app

COPY target/app.jar .

EXPOSE 8080

ENV SPRING_PROFILES_ACTIVE=dev

ENTRYPOINT ["java", "-jar", "app.jar"]

By doing this, the default profile to run the image will be dev. After build the image [docker run -p 8080:8080 myapp:latest] if you run:

docker run -p 8080:8080 myapp:latest

The properties file used will be application-dev.yaml because the default value for SPRING_PROFILES_ACTIVE is set to dev (see the Dockerfile).

You can override the SPRING_PROFILES_ACTIVE value as follows:

docker run -p 8080:8080 -e SPRING_PROFILES_ACTIVE=staging myapp:latest

Conclusion

Managing configurations for different environments is a critical aspect of building robust, secure, and maintainable Spring Boot applications. By leveraging profiles, you can isolate environment-specific settings and reduce the risk of misconfiguration. Externalizing configuration through environment variables or command-line arguments provides flexibility, especially in containerized or cloud-based deployments.

For more advanced needs, tools like Spring Cloud Config or HashiCorp Vault offer centralized and secure ways to manage configurations and secrets across multiple services and teams.

In summary:

• Use Spring profiles to separate environment concerns.
• Never hardcode sensitive data or production settings.
• Externalize configurations for better control and portability.
• Adopt secure practices when dealing with secrets.

Taking the time to structure your configuration strategy properly pays off in the long run — making your application easier to deploy, scale, and troubleshoot.