The Definitive Engineering Guide to OpenJDK Docker Implementations

The deployment of Java applications within containerized environments has evolved from simple image wrapping to a complex ecosystem of specialized distributions. OpenJDK (Open Java Development Kit) Docker images serve as the foundational layer for millions of microservices, providing the necessary Java Runtime Environment (JRE) and Java Development Kit (JDK) to execute bytecode across diverse cloud infrastructures. In the current landscape of April 2026, the selection of an OpenJDK image is no longer a matter of simply choosing a version number, but rather a strategic decision involving base operating system stability, security patching cycles, and the specific requirements of the Continuous Integration and Continuous Deployment (CI/CD) pipeline.

The architectural challenge of running Java in containers historically centered on the Java Virtual Machine (JVM) and its ability to perceive resource constraints. In early iterations, the JVM failed to recognize that it was running inside a container, instead probing the host machine for CPU cores and available RAM. This discrepancy often led to catastrophic failures where the JVM would attempt to spawn garbage collector threads based on the host's 64-core processor while the container was restricted to 2 cores, resulting in excessive CPU throttling and memory allocation errors. Modern OpenJDK versions, specifically those from version 8 onwards in Linux containers, have been engineered to correctly detect container-limited resources, ensuring that internal JVM parameters are tuned to the actual limits imposed by the container orchestrator.

The State of the Official Docker Hub OpenJDK Image

The official openjdk image on Docker Hub has undergone a significant lifecycle shift. It is currently classified as officially deprecated. This deprecation is not an indication that Java cannot be run in Docker, but rather a shift in how official images are maintained. The Docker Community, which previously maintained these images, now recommends that users migrate to suitable replacements as soon as possible to ensure long-term support and security updates.

The transition away from the official openjdk image is detailed in the docker-library/openjdk repository. While the image remains available, the maintenance window for most tags ended in July 2022. The only exceptions to this deprecation are the Early Access (EA) builds. Because Early Access builds are sourced directly from jdk.java.net, they continue to receive updates, as they are not supported or published by the same projects that maintained the stable releases.

Early Access and Experimental Tags

For developers tracking the bleeding edge of Java evolution, the openjdk repository continues to provide Early Access builds. These are critical for testing new language features before they reach General Availability (GA). Current tags include a vast array of combinations based on the version, the build stage, and the underlying OS.

The following table details the available Early Access configurations and their specific footprints:

The availability of these tags allows developers to test Java 27 features across diverse environments, including the latest Debian-based distributions like Trixie and Bookworm, as well as enterprise-grade Oracle Linux environments. The "slim" variants are particularly valuable for reducing the attack surface and decreasing the pull time of the image by removing non-essential packages.

CircleCI Convenience Images: cimg/openjdk

CircleCI provides a specialized set of Docker images known as "convenience images," designed specifically for the requirements of continuous integration. The cimg/openjdk image is engineered to supersede the legacy circleci/openjdk image, offering a more robust toolset for modern build pipelines.

These images are not merely JREs; they are fully equipped environments containing the JDK and all necessary binaries required for a build to complete successfully within a CircleCI environment. This eliminates the need for developers to manually install build tools via apt-get during the job execution, which would otherwise increase build times and introduce potential points of failure.

Specialized Variants and Functional Extensions

CircleCI recognizes that modern software development often involves polyglot architectures. To address this, they provide variant images that combine Java with other runtime environments.

• Node.js Variant: This image is created by appending -node to the base tag (e.g., cimg/openjdk:15.0-node). It provides both the OpenJDK environment and the Node.js runtime, which is essential for projects that use Java for the backend and a JavaScript framework for the frontend.
• Browsers Variant: This image is created by appending -browser to the tag. It includes Node.js, Selenium, and all necessary browser dependencies pre-installed via apt. This is specifically designed for end-to-end (E2E) testing where Java-based Selenium tests must drive a real browser instance.

An example implementation in a .circleci/config.yml file for a Java 15 environment would look as follows:

yaml jobs: build: docker: - image: cimg/openjdk:15.0 steps: - checkout - run: java --version

Red Hat Enterprise Solutions: ubi8/openjdk-21

For enterprise environments requiring high levels of security, compliance, and support, Red Hat provides the ubi8/openjdk-21 image. This image is built upon the Universal Base Image (UBI), which is designed to be a consistent foundation for containers across different platforms.

The Red Hat OpenJDK 21 container is specifically designed as a base platform for building and running plain Java 21 applications, supporting both fat-jar and flat classpath configurations. A distinguishing feature of this image is the integration of Source-to-Image (S2I) scripts, which facilitate seamless deployment on Red Hat OpenShift.

Technical specifications for the ubi8/openjdk-21 image include:

• Repository Name: ubi8/openjdk-21
• Image Version: 1.23
• Maintainer: Red Hat OpenJDK ([email protected])
• Architecture: amd64
• Exposed Ports: 8080/tcp, 8443/tcp
• Default User: 185
• Working Directory: /home/jboss

The use of a non-root user (UID 185) and a specific working directory (/home/jboss) reflects Red Hat's commitment to the principle of least privilege, reducing the risk of container escape vulnerabilities in production environments.

Microsoft Build of OpenJDK: mcr.microsoft.com

Microsoft provides a comprehensive suite of OpenJDK images tailored for Azure and general Linux distributions. These images are hosted on the Microsoft Container Registry (MCR) and can be pulled using the command docker pull mcr.microsoft.com/openjdk/jdk:<tag>.

Microsoft's offerings are segmented by the base operating system and the JDK version, providing a matrix of options for the developer.

Base OS Matrix and JDK Versioning

The following table outlines the supported combinations for Microsoft's OpenJDK images:

It is important to note that the OpenJDK 8 images provided by Microsoft utilize binaries from Eclipse Temurin, a project under the Eclipse Adoptium umbrella. Additionally, Microsoft has rebranded its Linux distribution; tags that were previously identified as -mariner (e.g., 21-mariner) now mirror the -azurelinux tags.

The "distroless" variants are particularly significant for security-conscious organizations. Distroless images contain only the application and its runtime dependencies, omitting shell utilities, package managers, and other binaries that are not needed for the application to run. This drastically reduces the vulnerability surface area by removing tools that an attacker could use once they gain access to a container.

Practical Implementation and Compilation Strategies

Implementing an OpenJDK Docker environment requires an understanding of how to structure the Dockerfile for both development and production.

Standard Compilation and Execution

The most common pattern involves using the image as a base to compile and then run the application. A typical Dockerfile for a Java application would appear as follows:

dockerfile FROM openjdk:11 COPY . /usr/src/myapp WORKDIR /usr/src/myapp RUN javac Main.java CMD ["java", "Main"]

To build and execute this image, the following commands are used:

bash docker build -t my-java-app . docker run -it --rm --name my-running-app my-java-app

External Compilation via Volume Mounting

In scenarios where it is inappropriate or inefficient to run the application inside a container—such as during a rapid development cycle where the code changes frequently—Docker can be used as a standalone compiler. By mounting the current working directory as a volume, the developer can use the OpenJDK image to compile the code without creating a full image.

The command to achieve this is:

bash docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp openjdk:11 javac Main.java

In this operation, -v "$PWD":/usr/src/myapp maps the host's current directory to the container's file system, and -w /usr/src/myapp sets the working directory. The resulting Main.class file is written back to the host's disk, allowing the developer to keep the compiled bytecode outside the container.

Comparative Analysis of OpenJDK Distributions

The choice of an OpenJDK image depends on the specific requirements of the project, ranging from development speed to production stability.

• For CI/CD Pipelines: cimg/openjdk is the optimal choice due to its pre-installed build tools and specialized variants for Node.js and browser testing.
• For Enterprise Production: ubi8/openjdk-21 provides the highest level of security and integration with OpenShift, making it ideal for regulated industries.
• For Cloud-Native Azure Deployments: mcr.microsoft.com/openjdk offers a seamless integration with Azure Linux and provides distroless options for maximum security.
• For Experimental Development: The openjdk official images (specifically EA tags) are the only viable option for testing features of upcoming Java releases like Java 27.

Conclusion

The ecosystem of OpenJDK Docker images has shifted from a centralized "one size fits all" model to a fragmented but specialized landscape. The deprecation of the general openjdk official image marks a transition toward vendor-backed and purpose-built distributions. Developers must now weigh the trade-offs between the convenience of CircleCI's tool-heavy images, the security of Red Hat's UBI and Microsoft's distroless images, and the agility of Early Access builds. The critical technical evolution in this space has been the JVM's ability to accurately sense container resource limits, which has stabilized the performance of Java applications in Kubernetes and other orchestrators. Selecting the correct image now requires an analysis of the base OS, the specific JDK version, and the target deployment environment to ensure a balance between image size, security, and runtime performance.

Sources

1. CircleCI OpenJDK Docker Hub
2. Docker Library OpenJDK GitHub
3. OpenJDK Tags Docker Hub
4. OpenJDK Official Image Docker Hub
5. Red Hat Ecosystem Catalog - OpenJDK 21
6. Microsoft Learn - OpenJDK Containers