Containerization has become a core practice in modern software development, especially for teams building scalable microservices. Spring Boot applications are no exception—packaging them into Docker containers helps ensure consistency, portability, and fast deployment across different environments.

In this guide, you’ll learn how to containerize a Spring Boot application using Docker, from preparing your app to building and running the image. The article is beginner-friendly but detailed enough for production-grade work.

Why Containerize a Spring Boot Application?

Before diving into the steps, it’s worth understanding why developers containerize Spring Boot apps:

1. Consistent Runtime Environment

A Docker image includes everything your app needs: JDK, dependencies, and configurations. No more “works on my machine” problems.

2. Easy Deployment & Scalability

Containers make it seamless to deploy on Kubernetes, AWS ECS, Docker Swarm, or any modern CI/CD pipeline.

3. Fast Build & Release Cycles

Build once, run anywhere. This reduces friction between Dev, QA, and Production environments.

Prerequisites

Before starting, make sure you have:

• Java 17+ or your project’s preferred version
• A working Spring Boot project (Maven or Gradle)
• Docker installed on your machine
• Basic familiarity with command-line operations

Step-by-Step Guide to Containerizing Your Spring Boot App

1. Package Your Spring Boot Application

First, generate a JAR file of your application.

For Maven:

mvn clean package

The JAR will be inside the target/ directory.

For Gradle:

./gradlew build

The JAR appears inside the build/libs/ folder.

2. Create a Dockerfile

A Dockerfile defines how your application should be built into an image.

Below is a recommended lightweight, production-ready Dockerfile using a multi-stage build:

# ===== STAGE 1: Build the JAR =====
FROM maven:3.9.6-eclipse-temurin-21 AS build
WORKDIR /app
COPY . .
RUN mvn clean package -DskipTests

# ===== STAGE 2: Create the runtime image =====
FROM eclipse-temurin:21-jre
WORKDIR /app

# Copy only the built JAR file from the previous stage
COPY --from=build /app/target/*.jar app.jar

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

Why this Dockerfile works well

• Multi-stage build reduces final image size
• Uses Eclipse Temurin JRE (lightweight, secure, stable)
• Keeps build dependencies out of the runtime layer
• Exposes port 8080, the default Spring Boot port

3. Build the Docker Image

Run the following command in the same directory as your Dockerfile:

docker build -t springboot-docker-demo .

This command will:

• Download the base images (on first run)
• Compile your Spring Boot project
• Package everything into a Docker image called springboot-docker-demo

4. Run the Docker Container

Once the image is built, spin up a container:

docker run -d -p 8080:8080 --name springboot-app springboot-docker-demo

Explanation:

• -d → run in detached mode
• -p 8080:8080 → expose app port to your host
• --name springboot-app → give the container a friendly name

Now open:

http://localhost:8080

If your Spring Boot app runs normally, you’ve successfully containerized it!

5. Verify Running Containers

To check container status:

docker ps

To see logs:

docker logs springboot-app

6. Stop and Remove Containers

If you need to stop the container:

docker stop springboot-app

Remove it:

docker rm springboot-app

Remove the image:

docker rmi springboot-docker-demo

Best Practices for Containerizing Spring Boot Applications

Here are some tips to ensure your containerized Spring Boot app performs well in production:

1. Use a Specific JDK/JRE Version

Avoid using generic tags like latest. Pin a specific version:

eclipse-temurin:21-jre

This improves reproducibility and reduces unexpected runtime issues.

2. Externalize Application Configuration

Spring Boot supports:

• environment variables
• application.yml or application.properties
• Kubernetes ConfigMaps/Secrets

Example:

docker run -e SPRING_PROFILES_ACTIVE=prod ...

3. Use Docker Ignore (.dockerignore)

Prevent unnecessary files from being copied into your image:

target/
.idea/
.git/
node_modules/

This improves build speed and security.

4. Optimize JVM Settings for Containers

Spring Boot + Java 21 already behaves well with containers, but you can further tune memory:

JAVA_OPTS="-Xms512m -Xmx512m"
docker run -e JAVA_OPTS="$JAVA_OPTS" ...

5. Use Health Checks

Let orchestrators know your app is healthy:

HEALTHCHECK CMD curl --fail http://localhost:8080/actuator/health || exit 1

Requires enabling Actuator in Spring Boot.

Containerizing Spring Boot: Common Issues

1. JAR Not Found

Double-check the build path and wildcard:

COPY --from=build /app/target/*.jar app.jar

2. Port Already in Use

Change mapping:

docker run -p 9090:8080 ...

3. Memory Constraints

Java may crash inside small containers. Tune with JAVA_OPTS.

Conclusion

Containerizing a Spring Boot application with Docker is a powerful way to improve portability, deployment consistency, and scalability. By using a multi-stage Dockerfile and following best practices for JVM tuning, configuration management, and image optimization, you can build efficient and production-ready containers.

Once your application is containerized, you can integrate it with CI/CD pipelines, deploy it to cloud services, or orchestrate it with Kubernetes—unlocking the full potential of modern DevOps workflows.