Skip to main content
Version: Current (3.x)

Recommended Docker Images for Backend Services

This document outlines the recommended Docker images for building and running backend services in the data-viz project. Individual projects and services need to be updated separately to use these recommended images.

Overview​

The data-viz project recommends using Eclipse Temurin-based Docker images for Java development and runtime. Eclipse Temurin is the open-source distribution of the OpenJDK, maintained by the Eclipse Adoptium project, providing reliable and well-maintained Java runtime environments.

Maven Build Image​

Image: maven:3-eclipse-temurin-21

Use this image for building Java applications with Maven.

FROM maven:3-eclipse-temurin-21 AS compiler
WORKDIR /opt/viz
# ... your build steps

Why this image?

  • Combines Maven 3 with Eclipse Temurin JDK 21
  • Provides a consistent build environment
  • Well-maintained and regularly updated
  • Suitable for CI/CD pipelines

Image: eclipse-temurin:21-jre-alpine

Use this image for running Java applications in production environments.

FROM eclipse-temurin:21-jre-alpine
WORKDIR /opt/viz
COPY --from=compiler /opt/viz ./
# ... your runtime configuration

Why this image?

  • Alpine-based: Smaller image size, reducing deployment footprint and improving security
  • JRE only: Contains only the Java Runtime Environment, not the full JDK
  • Production-optimized: Minimal image size while maintaining full runtime capabilities
  • Security: Alpine Linux provides a smaller attack surface
  • Performance: Smaller images mean faster pulls and deployments

When to use: Production deployments where you only need to run compiled Java applications.

JDK Runtime Image​

Image: eclipse-temurin:21-jdk-alpine

Use this image when you need development tools or compilation capabilities at runtime.

FROM eclipse-temurin:21-jdk-alpine
WORKDIR /opt/viz
# ... your configuration

Why this image?

  • Full JDK: Includes development tools, compilers, and debugging utilities
  • Alpine-based: Smaller than standard JDK images
  • Development-friendly: Useful for development environments or when runtime compilation is needed

When to use:

  • Development environments
  • Applications that require runtime compilation
  • Debugging scenarios where development tools are needed

Note: The JDK image is larger than the JRE image. Use JRE for production unless you specifically need JDK features.

Alternative Eclipse Temurin Images​

You can use other Eclipse Temurin images, but they will be larger:

Standard Images (Larger)​

  • eclipse-temurin:21-jre - Standard JRE (larger than Alpine)
  • eclipse-temurin:21-jdk - Standard JDK (larger than Alpine)
  • eclipse-temurin:21-jre-jammy - Ubuntu-based JRE
  • eclipse-temurin:21-jdk-jammy - Ubuntu-based JDK

When to consider alternatives:

  • If you need specific system libraries not available in Alpine
  • If you encounter compatibility issues with Alpine's musl libc
  • If your application requires glibc-based distributions

Trade-offs:

  • Larger image sizes (typically 1.5-3x larger than Alpine)
  • More system packages and dependencies
  • Potentially longer build and pull times

Migration Guide​

Updating Build Images​

If your project currently uses Amazon Corretto or other Maven images:

Before:

FROM maven:3-amazoncorretto-21 AS compiler

After:

FROM maven:3-eclipse-temurin-21 AS compiler

Updating Runtime Images​

If your project currently uses OpenJDK or other runtime images:

OpenJDK Images Deprecation Notice
Important Notes
  • OpenJDK images were deleted from the Docker Registry.
  • You should use the Eclipse Temurin images instead.
  • See the deprecation notice here

Before:

# OpenJDK images were deleted.
FROM openjdk:21-jdk-slim

After (Production - Recommended):

FROM eclipse-temurin:21-jre-alpine

After (Development/Debugging):

FROM eclipse-temurin:21-jdk-alpine

Example Multi-stage Dockerfile​

Here's a complete example using the recommended images:

# Build stage
FROM maven:3-eclipse-temurin-21 AS compiler
WORKDIR /opt/viz

COPY ./pom.xml ./pom.xml
RUN --mount=type=cache,target=/root/.m2 \
    mvn -B dependency:go-offline

COPY ./src ./src
RUN --mount=type=cache,target=/root/.m2 \
    mvn -B package -DskipTests

# Runtime stage (Production)
FROM eclipse-temurin:21-jre-alpine
WORKDIR /opt/viz

# Install curl for health checks (if needed)
RUN apk add --no-cache curl

COPY --from=compiler /opt/viz/target/*.jar app.jar
COPY ./entrypoint.sh ./entrypoint.sh
RUN chmod +x ./entrypoint.sh

EXPOSE 8080

ENTRYPOINT ["./entrypoint.sh"]

Image Size Comparison​

Approximate image sizes (may vary by version):

ImageSize
eclipse-temurin:21-jre-alpine~65-70 MB
eclipse-temurin:21-jdk-alpine~170-175 MB
eclipse-temurin:21-jre~90-100 MB
eclipse-temurin:21-jdk~200-250 MB
maven:3-eclipse-temurin-21~225-240 MB
maven:3-eclipse-temurin-21-alpine~180-190 MB

Note: Alpine-based images are significantly smaller, making them ideal for production deployments.

Important Notes
  • Alpine images do come pre-installed with bash, curl, and other useful tools.
  • Alpine images are not compatible with glibc.
  • You can add other tools to the image by adding them to the Dockerfile.
  • Alpine images use busybox as the default shell, which is a minimal shell that is very fast and small. Therefore, if you need to use a different shell (e.g., bash), you can add it to the Dockerfile.

Best Practices​

  1. Use Alpine for production: Prefer -alpine variants for smaller images and faster deployments
  2. Use JRE when possible: Only use JDK if you need compilation or development tools at runtime
  3. Multi-stage builds: Use separate build and runtime stages to keep final images small
  4. Cache Maven dependencies: Use Docker build cache mounts for Maven dependencies to speed up builds
  5. Pin versions: Consider pinning to specific versions for reproducibility (e.g., eclipse-temurin:21.0.1-jre-alpine)
  6. Health checks: Add health check endpoints and use curl or wget in Alpine images for health checks

Updating Individual Services​

Each service in the data-viz project should be updated separately:

  1. Update the service's Dockerfile to use the recommended images
  2. Test the build to ensure compatibility
  3. Update CI/CD pipelines (e.g., Jenkinsfile) if they reference specific images
  4. Verify runtime behavior in both development and production environments