Dockerize a Kotlin App with Multi-Stage Builds

By Khimananda Oli | Last reviewed: August 2026

Kotlin applications compiled on the JVM often result in Docker images exceeding 800MB when built naively, creating slow deployments and expanded attack surfaces. To Dockerize a Kotlin app with multi-stage builds effectively, you must separate the compilation environment from the runtime environment within your Dockerfile. This approach discards the JDK, Gradle caches, and source code after building, leaving only the minimal JRE and application artifacts required for execution.

How do you structure a multi-stage Dockerfile for Kotlin?

The architecture of an efficient Kotlin container relies on isolating dependencies that are strictly necessary for compilation from those needed at runtime. When you Dockerize a Kotlin app with multi-stage builds, you are essentially creating two distinct environments in a single file. The first stage acts as a factory; the second acts as the shipping container.

In practice, the most common mistake engineers make is failing to leverage Gradle's dependency caching layer. If you copy your entire project directory before running the build, every source code change invalidates the Docker layer cache, forcing a full re-download of dependencies. Instead, structure your Dockerfile to copy build.gradle.kts and settings.gradle.kts first, run a dependency resolution task, and only then copy the source code. This pattern is critical for fast CI/CD pipelines, especially when working with teams across Nepal and global time zones where build feedback loops directly impact velocity.

Defining the builder stage correctly

Your builder stage should use a full JDK image matching your target Java version. For Kotlin 2.x projects in 2026, Java 21 LTS is the standard baseline. Use the official Eclipse Temurin images for consistent, license-friendly builds. Always set the working directory explicitly and configure Gradle to avoid running as root, which prevents permission issues when copying artifacts to the final stage.

# Stage 1: Builder
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app

# Copy gradle wrapper and config first for better caching
COPY gradlew settings.gradle.kts build.gradle.kts ./
COPY gradle ./gradle

# Download dependencies (cached unless build files change)
RUN chmod +x gradlew && ./gradlew dependencies --no-daemon

# Now copy source and build
COPY src ./src
RUN ./gradlew bootJar --no-daemon --stacktrace

Configuring the runtime stage for minimal footprint

The runtime stage should never contain a compiler, shell utilities, or package managers unless absolutely required for debugging. Use eclipse-temurin:21-jre-alpine or the newer eclipse-temurin:21-jre-noble if you require glibc compatibility for specific native libraries. Create a non-root user, set appropriate file permissions, and expose only the necessary ports. This aligns with the principles discussed in container image scanning with Trivy, where reducing the number of installed packages directly correlates to fewer CVE findings.

What is the optimal Gradle configuration for containerized Kotlin builds?

Gradle behaves differently inside containers than on developer workstations. Without proper tuning, you will encounter out-of-memory errors during compilation or excessively long build times due to daemon overhead. When you Dockerize a Kotlin app with multi-stage builds, the Gradle daemon provides no benefit because each Docker layer is immutable; the daemon cannot persist state between runs.

• Disable the daemon: Always pass --no-daemon to Gradle commands in Dockerfiles. The daemon startup cost exceeds its benefit in ephemeral build environments.
• Enable parallel execution: Add org.gradle.parallel=true to your gradle.properties to utilize all available CPU cores during compilation.
• Configure memory limits: Set org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m to prevent the JVM from consuming all container memory and triggering OOM kills.
• Use reproducible builds: Enable tasks.withType<AbstractArchiveTask> { isPreserveFileTimestamps = false; isReproducibleFileOrder = true } in your build script to ensure identical inputs produce byte-for-byte identical outputs, improving layer cache hit rates.

For teams managing multiple microservices, consider applying these settings globally through a shared convention plugin rather than repeating them in every Dockerfile. This reduces drift and ensures consistent build behavior across your portfolio, whether you are deploying to AWS EKS or a local Kubernetes cluster as described in Amazon EKS practical guide.

Handling Kotlin-specific compilation nuances

Kotlin's incremental compilation can cause issues in Docker if not configured properly. The Kotlin compiler maintains caches that may become stale across layer boundaries. In your build.gradle.kts, explicitly configure the Kotlin JVM target to match your runtime JRE version. Mismatched targets (e.g., compiling with Java 21 but targeting Java 17 bytecode while running on Java 21) work but miss performance optimizations available in newer bytecode versions.

kotlin {
    jvmToolchain(21)
}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
    compilerOptions {
        freeCompilerArgs.addAll("-Xjsr305=strict", "-Xemit-jvm-type-annotations")
    }
}

How do you reduce Kotlin Docker image size below 200MB?

Image size directly impacts deployment speed, autoscaling responsiveness, and storage costs. A typical unoptimized Kotlin Spring Boot image weighs 800–950MB. After applying multi-stage builds correctly, you should target 150–190MB for most web applications. The difference lies in base image selection and artifact optimization.

For most Kotlin web applications in 2026, Alpine-based JRE images offer the best balance. However, if your application uses JNI libraries like netty-tcnative or certain cryptography providers, musl libc incompatibilities may cause runtime failures. In such cases, use the Ubuntu Noble-based slim JRE variant instead. Always validate your choice by running integration tests against the actual production image, not just the builder output.

Advanced optimization with jlink

If you need to go below 150MB, use jlink to create a custom runtime containing only the Java modules your Kotlin application actually uses. This requires analyzing your dependencies with jdeps first. While more complex to maintain, this approach is valuable for serverless deployments or edge computing scenarios where every megabyte affects cold start latency and billing. Document your module list in version control so future developers understand why specific modules were included.

How do you handle secrets and security in Kotlin container builds?

Security cannot be an afterthought when containerizing JVM applications. Build-time secrets (like private Maven repository credentials) must never appear in image layers. Runtime secrets should be injected via environment variables or mounted volumes, never baked into the JAR. This discipline is essential for passing SOC 2 audits and maintaining compliance in regulated environments.

1. Use BuildKit secret mounts: Pass sensitive build arguments using RUN --mount=type=secret,id=gradle_properties,target=/root/.gradle/gradle.properties instead of ARG directives. Secrets mounted this way never persist in any layer.
2. Create a non-root user: Always add RUN addgroup -S appgroup && adduser -S appuser -G appgroup and switch to it with USER appuser before the ENTRYPOINT. Running as root inside containers violates least-privilege principles and enables container escape vulnerabilities.
3. Set read-only filesystems: Configure your container runtime to mount the root filesystem as read-only, with explicit tmpfs mounts for directories requiring write access (/tmp, log directories). This prevents attackers from modifying binaries post-exploitation.
4. Scan before pushing: Integrate vulnerability scanning into your CI pipeline. Tools like Trivy or Grype should fail builds on critical CVEs. Refer to DevSecOps shift-left practices for implementation patterns that catch issues before they reach production registries.

Managing Gradle private repository authentication

Many organizations host internal Kotlin libraries on private Artifactory or Nexus instances. Authenticating during Docker builds requires careful handling. Store credentials in your CI system's secret store, mount them during the dependency resolution phase, and ensure they are not copied into subsequent stages. Never commit gradle.properties containing passwords to version control, even if gitignored — accidental commits happen frequently under deadline pressure.

# Secure dependency resolution with BuildKit secrets
RUN --mount=type=secret,id=gradle_creds,target=/root/.gradle/gradle.properties \
    ./gradlew dependencies --no-daemon

# Credentials are NOT present in this or any subsequent layer
COPY src ./src
RUN ./gradlew bootJar --no-daemon

What are common pitfalls when Dockerizing Kotlin applications?

Even experienced engineers encounter subtle issues when transitioning Kotlin applications to containers. Understanding these failure modes prevents production incidents and debugging sessions at inconvenient hours.

• Timezone mismatches: Alpine images default to UTC. If your Kotlin code uses LocalDateTime.now() without explicit timezone configuration, logs and business logic timestamps will differ from your Nepal-based team's expectations. Set TZ=Asia/Kathmandu in your Dockerfile or configure the JVM with -Duser.timezone=Asia/Kathmandu.
• Missing CA certificates: Minimal JRE images sometimes lack complete certificate bundles. If your application calls external HTTPS APIs and fails with SSL handshake errors, install ca-certificates package in your runtime stage or use a base image known to include them.
• Incorrect health check paths: Spring Boot Actuator endpoints may be disabled or secured in production profiles. Verify your HEALTHCHECK directive targets an accessible endpoint that accurately reflects application readiness, not just HTTP 200 responses.
• Ignoring SIGTERM handling: Kotlin applications must gracefully shut down when receiving termination signals. Ensure your entrypoint uses exec form (ENTRYPOINT ["java", "-jar", "app.jar"]) rather than shell form to allow signal propagation. Without this, Kubernetes pod terminations will always hit the grace period timeout, causing request drops during rolling updates.

Debugging layer cache misses

When builds suddenly take 10 minutes instead of 30 seconds, layer cache invalidation is usually the culprit. Use docker build --progress=plain to see exactly which layer broke the cache. Common causes include non-deterministic file ordering in COPY commands, timestamp differences, or unintended modifications to gradle wrapper scripts. Pin your Gradle wrapper version in version control and verify checksums to ensure reproducibility across developer machines and CI runners.

Deploying Optimized Kotlin Containers Effectively

Successfully implementing multi-stage builds is only half the equation. You must also configure your orchestration platform to leverage the smaller images effectively. Set appropriate resource requests and limits based on actual profiling, not guesses. A 180MB Kotlin container typically needs 256–512MB memory limit depending on heap configuration. Monitor garbage collection metrics to tune JVM flags like -XX:MaxRAMPercentage=75.0 rather than hardcoding heap sizes, which breaks when container limits change. For comprehensive observability setup post-deployment, review Prometheus and Grafana monitoring stack to ensure your optimized containers remain visible and debuggable in production.

If your team is adopting containerized Kotlin services and needs guidance on secure, compliant deployment patterns, reach out to discuss your infrastructure requirements. Proper containerization foundations prevent costly rework during security audits and scaling events.