Developer Tools & Environments ADVANCED Linux / macOS (Docker) โฑ๏ธ 4 min read ๐Ÿ“… Updated: 22 Nov 2026

Advanced: Benchmarking & Optimizing Build Artifact Size with Docker Multi-Stage Builds

This guide teaches advanced developers how to significantly reduce the final size of container images by mastering multi-stage builds and implementing layer deduplication techniques within Dockerfiles.

Gurveer Singh
Gurveer Singh โœ“ Verified Specialist
Founder & Chief Architect ยท hSECURITIES Labs
โšก FAST-TRACK PROTOCOL

Direct Diagnostic & Remediation Summary

  • Action 1: Always use a minimal base image in your final stage (e.g., scratch, alpine) instead of the builder image.FROM --platform=linux/arm64 alpine:latest.
  • Action 2: Copy only necessary artifacts from the build stage using explicit commands like COPY --from=builder /path/to/artifact /app/.
๐Ÿ› ๏ธ Tools & Prerequisites: Docker Engine installed and running (version 18.09+ recommended), a sample application repository containing source code, and basic understanding of Dockerfile syntax.
๐Ÿ” Root Cause & Diagnostic Overview: The primary cause of bloated container images is the inclusion of build dependencies, compilers, large SDKs, intermediate files, and development toolchains (like Maven/Gradle caches or Node_modules) in the final runtime image. Docker layers are cumulative; if a layer contains unnecessary data, that space persists unless explicitly pruned or excluded. Multi-stage builds mitigate this by running compilation/downloading in one stage and copying only the necessary compiled output to a clean, minimal base image in a subsequent stage.
STEP 1

Analyze Current Image Bloat & Establish Baseline

Before optimizing, you must quantify the problem. Run your current build process and inspect the resulting image layers to identify excessive data retention.

  • Inspect Layers: Use docker history : to see layer changes. Pay attention to large additions in early stages that persist late.
  • Audit Size: Run docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" on the problematic image to get a baseline size measurement.
STEP 2

Implement Multi-Stage Build Structure

Refactor your Dockerfile into at least two distinct stages: the builder stage (for compilation/dependencies) and the final_runtime stage (for execution).

# Stage 1: The Builder
FROM maven:3.8.6-openjdk-17 AS builder
WORKDIR /app
COPY .mvn/ ./.mvn
COPY pom.xml .
COPY src ./src

RUN mvn clean package -DskipTests

This first stage contains all the heavy tools (Maven, JDK), which we do not want in the final image.

STEP 3

Isolate and Copy Artifacts for Final Runtime

The key to deduplication is selective copying. In the second stage, start from a minimal base OS and only copy the final, immutable artifact.

# Stage 2: The Final Runtime Image
FROM eclipse-temurin:17-jre-alpine AS final_runtime
WORKDIR /app

# IMPORTANT: Only copy the JAR/binary artifact, not the entire build directory.
COPY --from=builder /app/target/my-application-*.jar app.jar

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

By using --from=builder and specifying only the required file (app.jar), Docker ensures that all intermediate build tools from Stage 1 are discarded, drastically reducing the final layer size.

STEP 4

Advanced Optimization: Cleaning Caches and Dependencies

Even after multi-staging, build tools might leave caches. Always run explicit cleanup commands in the builder stage.

  • Clean Package Manager Cache: If using npm/yarn, add RUN npm cache clean --force before the final copy.
  • Remove Build Directories: Explicitly remove large directories that are not needed for runtime, such as rm -rf /root/.cache/* in the builder stage.
TROUBLESHOOTING

Common Pitfalls & Advanced Diagnostics

If the size reduction is minimal, check these common pitfalls:

  • Pitfall: Copying Build Contexts: Accidentally using COPY . . in the final stage copies everything from the build context into every layer. Always use targeted COPY --from=builder ....
  • Pitfall: Non-Ephemeral Dependencies: If your application requires runtime libraries (e.g., specific native codecs), ensure they are installed in the minimal base image (Alpine/Distroless) using their package manager (apk add --no-cache ...).
FINAL STEP

Verification, Results & Long-Term Stability Validation

After rebuilding the image using the optimized Dockerfile, verify the size reduction and test runtime functionality.

  • Rebuild: docker build -t optimized-app:latest .
  • Verify Size: Compare docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" for the new tag against your initial baseline size.
  • Test Execution: Run a smoke test to ensure the minimal base image did not strip necessary runtime libraries: docker run --rm optimized-app:latest /bin/sh -c "echo Success"`
  • Prevention Tip: Adopt 'Distroless' images (Google) for maximum security and minimum size when possible, as they contain only the application and its direct runtime dependencies.
Resolution Complete: By implementing multi-stage builds and strictly controlling what artifacts are copied to the final stage, you successfully minimized the Docker image footprint by discarding development toolchains and build caches. If performance degrades after optimization, review Step 4 to ensure no necessary runtime dependencies were accidentally removed from the base image.
COMMAND LINE / TERMINAL
docker history <image_name>:<tag>
docker images --format "{{.Repository}}:{{.Tag}}	{{.Size}}"
docker build -t optimized-app:latest .

Frequently Asked Questions

What is the difference between multi-stage builds and simply cleaning up in one stage?

Multi-stage builds are superior because they create an entirely separate, clean environment (the final stage) that inherits only what you explicitly copy. Cleaning up in one stage still leaves the initial massive layer containing all tools, even if later commands delete them.

Which base image is best for smallest size?

For maximum reduction and security, consider Google's Distroless images or Alpine Linux if your application supports it. Avoid standard OS distributions unless necessary.

What happens if I forget to copy a necessary runtime library in the final stage?

The container will fail at <code>docker run</code> time with an error like 'command not found' or 'library missing,' indicating a dependency gap.

Engineering Assistance

Need help implementing this solution?

Our cybersecurity and infrastructure engineers can audit, harden, or configure your systems directly.

Request Technical Assistance โ†’
Gurveer Singh
Gurveer Singh โœ“ Verified Author
Founder & CEO at hSECURITIES | Cybersecurity Educator | Security Researcher | Ethical Hacking Enthusiast | Technology Mentor
Meet the Founder โ†’

Gurveer Singh Saggu is the Founder and CEO of hSECURITIES, a cybersecurity and technology education platform focused on practical learning, digital security awareness, hardware diagnostics, Linux administration, and real-world cybersecurity training.

With a strong passion for technology, ethical hacking, and security education, he has spent years helping students, professionals, and organizations understand modern cyber threats and develop practical technical skills. Through hSECURITIES, he creates hands-on learning resources, technical guides, security awareness content, and community-driven initiatives that make cybersecurity more accessible.

His mission is to bridge the gap between theoretical knowledge and practical implementation by providing step-by-step learning experiences, technical troubleshooting resources, and security-focused educational platforms.

Community Discussion & Confirmations (0)

Technical questions, hardware findings, and verified fix reports.

No reader questions posted yet. Have you tried this solution or experienced an edge case? Post below.

Ask a Question or Share Solution