Introduction

Running a Spring Boot application in Docker with a specific profile is usually just a matter of setting the active profile at container startup. The most common approaches are the SPRING_PROFILES_ACTIVE environment variable or the --spring.profiles.active command-line argument.

Use Spring profile-specific configuration files

Spring Boot loads profile-specific files such as:

• 'application-dev.properties'
• 'application-prod.yml'

Those files live under src/main/resources and are activated when the matching profile is active. For example:

# application-dev.properties
server.port=8080
logging.level.root=DEBUG

# application-prod.properties
server.port=8080
logging.level.root=INFO

Docker does not change how profiles work. It just changes how you pass the active profile into the process.

Set the profile with an environment variable

The cleanest runtime approach is usually:

FROM eclipse-temurin:17-jre
COPY build/libs/app.jar /app/app.jar
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

Then start the container with:

docker run -e SPRING_PROFILES_ACTIVE=prod my-app

Spring Boot automatically reads that environment variable and activates the prod profile.

This is often the best option because the same image can run in multiple environments without rebuilding it.

You can also use a command-line argument

Another valid approach is to pass the property directly to the JVM process:

docker run my-app --spring.profiles.active=prod

This works because anything after the image name is appended as arguments to the process launched by ENTRYPOINT.

You can also bake a default into the Dockerfile with CMD:

1FROM eclipse-temurin:17-jre
2COPY build/libs/app.jar /app/app.jar
3ENTRYPOINT ["java", "-jar", "/app/app.jar"]
4CMD ["--spring.profiles.active=dev"]

Now the container defaults to dev, but callers can override it at runtime.

Docker Compose makes profile selection clearer

For local development, Docker Compose or Compose-compatible files often make profile configuration easier to see:

1services:
2  app:
3    image: my-app
4    environment:
5      SPRING_PROFILES_ACTIVE: prod
6    ports:
7      - "8080:8080"

This keeps the profile selection in versioned deployment configuration rather than hidden inside a shell history entry.

Prefer runtime configuration over image-specific rebuilds

A common mistake is creating separate images such as my-app-dev and my-app-prod just to switch Spring profiles. That increases image drift and makes promotion across environments harder.

The better pattern is usually:

• build one application image
• activate the desired profile through environment or arguments
• inject secrets and environment-specific values at runtime

That keeps the container image portable.

Remember that profiles and environment variables can interact

Spring profiles choose which configuration files are active, but normal environment variables can still override individual properties. That means you can run prod while also overriding one setting for a temporary test if needed.

This is powerful, but it also means you should document the intended precedence so operators know where the final value came from.

Common Pitfalls

• Hard-coding the profile into the image when the same image should serve multiple environments.
• Forgetting that SPRING_PROFILES_ACTIVE must match the profile-specific file name.
• Using CMD and assuming it cannot be overridden at runtime.
• Rebuilding the image for every environment instead of setting profile data at startup.
• Mixing profile configuration with secrets that should come from environment variables or a secret manager.

Summary

• The usual way to run Spring Boot in Docker with a profile is SPRING_PROFILES_ACTIVE.
• '--spring.profiles.active=... is an equally valid command-line alternative.'
• Dockerfiles should normally stay environment-neutral so one image can run everywhere.
• Compose files are a convenient place to declare profile activation for local or shared environments.
• Profiles choose configuration sets, but other environment variables can still override individual properties.