Dockerize a Quarkus Application

By Khimananda Oli | Last reviewed: August 2026

You need to dockerize a Quarkus application that starts in milliseconds, consumes minimal memory, and survives security audits. While standard Java containerization often results in bloated images exceeding 400MB, Quarkus offers a distinct advantage through GraalVM native compilation and optimized JVM modes. This guide provides the exact multi-stage Dockerfiles, build configurations, and hardening steps I use in production environments to achieve sub-50MB footprints and instant readiness.

How do you choose between native and JVM modes when you dockerize a Quarkus application?

The decision between native and JVM containerization dictates your entire build pipeline, resource allocation, and operational characteristics. In my experience managing microservices across AWS EKS and on-prem Kubernetes clusters, there is no universal "best" option—only the right trade-off for your specific workload.

Native Mode: Maximum Density

Native compilation uses GraalVM or Mandrel to perform ahead-of-time (AOT) compilation. The resulting binary includes only the code paths actually used, eliminating the JIT compiler and unused JDK libraries. This is ideal for serverless (AWS Lambda), high-density Kubernetes nodes, or edge deployments where memory costs dominate. Expect build times of 3–8 minutes depending on dependency complexity, but startup times under 50ms and RSS memory usage around 30–60MB.

JVM Mode: Development Velocity

The JVM mode packages your application as optimized bytecode running on a standard OpenJDK runtime. Quarkus still performs significant build-time augmentation, so it starts faster than Spring Boot, but not at native speeds. Choose this when debugging production issues (full stack traces, dynamic proxies), when using reflection-heavy libraries incompatible with AOT, or when CI build time matters more than runtime footprint. Images typically land at 180–250MB with startup times of 0.5–2 seconds.

What is the optimal multi-stage Dockerfile for Quarkus native builds?

A common mistake when teams first reduce Docker image size with multi-stage builds is neglecting cache efficiency or including build tools in the final artifact. The following Dockerfile is battle-tested for Quarkus 3.x native builds in 2026. It leverages the official Mandrel builder image, separates dependency resolution from compilation, and produces a distroless final image.

# Stage 1: Build the native executable
FROM quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21 AS build
WORKDIR /code
COPY --chown=quarkus:quarkus mvnw /code/mvnw
COPY --chown=quarkus:quarkus .mvn /code/.mvn
COPY --chown=quarkus:quarkus pom.xml /code/pom.xml
# Cache dependencies separately from source
RUN ./mvnw -B org.apache.maven.plugins:maven-dependency-plugin:3.6.1:go-offline
COPY src /code/src
RUN ./mvnw package -Pnative -DskipTests \
    -Dquarkus.native.container-build=true \
    -Dquarkus.package.type=native

# Stage 2: Minimal runtime
FROM registry.access.redhat.com/ubi8/ubi-micro:8.9
ENV LANGUAGE='en_US:en'
WORKDIR /work/
RUN chown 1001 /work \
    && chmod "g+rwX" /work \
    && chown 1001:root /work
COPY --chown=1001:root --from=build /code/target/*-runner /work/application
EXPOSE 8080
USER 1001
CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

Key Design Decisions

• Dependency Caching: The go-offline goal runs before copying src/. Changing business logic won't invalidate the expensive dependency download layer.
• UBI Micro Base: Red Hat’s UBI Micro contains no package manager, shell, or utilities. This reduces CVE surface area dramatically compared to Alpine or Debian slim.
• User 1001: Quarkus convention uses UID 1001. Never run as root in production; this violates CIS benchmarks and most compliance frameworks.
• Container Build Flag: -Dquarkus.native.container-build=true ensures the build happens inside the Mandrel container, avoiding host glibc mismatches.

How do you secure and harden a Quarkus container for production?

Security cannot be an afterthought when you dockerize a Quarkus application for regulated environments. I have helped teams pass SOC 2 and ISO 27001 audits by enforcing these baseline controls directly in the container definition.

Immutable Filesystem and Read-Only Roots

Configure your orchestrator to mount the root filesystem as read-only. Quarkus writes to /tmp and /work by default; explicitly mount these as emptyDir volumes in Kubernetes or tmpfs in Docker Compose. This prevents attackers from writing persistent payloads if they achieve RCE.

Pinned Image Digests

Never use mutable tags like latest or even jdk-21 in production Dockerfiles. Tags can be overwritten silently. Always pin to a SHA256 digest:

FROM registry.access.redhat.com/ubi8/ubi-micro@sha256:a1b2c3d4e5f6... AS runtime

This guarantees bit-for-bit reproducibility across builds and simplifies incident forensics. Store approved digests in a central configuration file or CI variable group.

Health Checks and Graceful Shutdown

Quarkus exposes /q/health/live and /q/health/ready automatically when the smallrye-health extension is present. Configure liveness probes with generous initial delays for JVM mode (10s) and aggressive ones for native (2s). Implement shutdown hooks to drain active requests before SIGTERM completes—critical for zero-downtime rolling updates on Kubernetes deployments.

How does Quarkus compare to Spring Boot for containerized Java workloads?

Engineers frequently ask whether migrating to Quarkus is justified solely for container density. The answer depends on your scaling model and team expertise. Below is a real-world comparison based on identical REST API workloads deployed to EKS in 2026.

For greenfield microservices, event-driven functions, or cost-sensitive cloud deployments, Quarkus native delivers tangible ROI. For monolithic applications with heavy reflection usage or teams deeply embedded in the Spring ecosystem, the migration tax may outweigh container savings. Evaluate based on total cost of ownership, not just image size.

Practical Checklist Before Shipping

Before pushing your Quarkus container to production, verify these items. Skipping any one has caused incidents in systems I’ve audited:

1. Run Trivy or Grype scans in CI. Fail the pipeline on HIGH/CRITICAL CVEs in the runtime layer. See container image scanning with Trivy for setup.
2. Validate health endpoints respond within probe timeouts under load. Test graceful shutdown with kill -SIGTERM locally.
3. Set resource limits explicitly. Native apps can still leak memory; JVM apps need heap tuning (-XX:MaxRAMPercentage=75). Reference Kubernetes resource limits and requests for sizing guidance.
4. Externalize configuration. Never bake secrets or environment-specific values into the image. Use ConfigMaps, Vault, or environment variables injected at runtime.
5. Tag with Git SHA, not semantic version alone. Enables instant rollback correlation during incidents.

Ship Production-Ready Quarkus Containers

When you correctly dockerize a Quarkus application, you gain a runtime that aligns with modern cloud economics: fast, lean, and secure by default. The multi-stage patterns and hardening practices outlined here reflect current production standards for 2026, balancing developer velocity with operational rigor. Whether you choose native for density or JVM for compatibility, the foundation remains the same: layered caching, minimal bases, and defense-in-depth.

If your team needs help optimizing Quarkus deployments, designing compliant container pipelines, or benchmarking against existing Spring Boot workloads, reach out to discuss your infrastructure. I help organizations ship faster without sacrificing security or observability.