niceos/openjdk21

☕ NiceOS OpenJDK 21

An alternative to Bitnami images — secure, minimal, reproducible container base.

Java 21 on a purpose-built container OS — minimal, predictable, and secure. Base OS: NiceOS Base → a container-first Linux engineered for clarity and safety (not a trimmed general-purpose distro). Learn more about the base at https://hub.docker.com/r/niceos/base-os.

https://img.shields.io/docker/pulls/niceos/openjdk21.svg](https://hub.docker.com/r/niceos/openjdk21) https://img.shields.io/badge/Base-NiceOS%20Base-blue](https://hub.docker.com/r/niceos/base-os) https://img.shields.io/badge/License-Apache%202.0-blue.svg](http://www.apache.org/licenses/LICENSE-2.0)

---

📌 Tag Policy (read this first)

This repository uses a stable-but-rolling strategy:

• Pinned build tags (e.g. 21.0.9_7) are immutable. Once published, they never change. Use these for deterministic CI/CD.
• Moving tags (e.g. 21.0.9, latest) can be updated to include security fixes, base OS refreshes, and OpenJDK updates for the same line. They are convenient for development but not guaranteed to stay the same digest.

Currently published tags:

• 21.0.9 — moving (updated over time within the same version line)
• 21.0.9_7 — pinned (immutable)
• latest — moving (tracks the newest stable image)

Production recommendation: pin to an immutable tag like 21.0.9_7. Development recommendation: use 21.0.9 or latest for convenience.

Note: there is no 21 tag.

---

TL;DR

Run Java (moving tag):

bash
docker run --rm niceos/openjdk21:21.0.9 java -version

Pin for production (immutable):

bash
docker run --rm niceos/openjdk21:21.0.9_7 java -version

Run your JAR:

bash
docker run --rm -v "$PWD"/app.jar:/app/app.jar niceos/openjdk21:21.0.9_7 \
  java -jar /app/app.jar

Docker Compose:

yaml
services:
  java:
    image: niceos/openjdk21:21.0.9_7
    volumes:
      - ./app.jar:/app/app.jar
    command: ["java", "-jar", "/app/app.jar"]

Kubernetes (minimal Deployment):

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-java
spec:
  replicas: 1
  selector: { matchLabels: { app: my-java } }
  template:
    metadata: { labels: { app: my-java } }
    spec:
      securityContext: { runAsUser: 10001, runAsGroup: 10001 }
      containers:
        - name: app
          image: niceos/openjdk21:21.0.9_7
          args: ["java","-jar","/app/app.jar"]
          volumeMounts:
            - name: appjar
              mountPath: /app/app.jar
              subPath: app.jar
          readinessProbe:
            exec: { command: ["java","-version"] }
            initialDelaySeconds: 5
            periodSeconds: 15
      volumes:
        - name: appjar
          configMap: { name: my-java-jar }

---

🧩 Overview

NiceOS OpenJDK 21 delivers a clean, production-ready Java 21 runtime on NiceOS Base — a Linux distribution built exclusively for containers. This is not “Java on a repackaged distro”; it’s Java on a container-first OS designed for minimalism, security, and reproducibility.

Core principles

• 🧹 Clean: no package managers, compilers, or background daemons.
• 🔒 Secure: each build is scanned; critical CVEs block release.
• ♻️ Rolling: monthly refreshes; out-of-band fixes for urgent issues.
• 🧾 Transparent: SBOM and vulnerability reports are embedded in the image.

---

🔄 Updates & Release Model

• Monthly refreshes after QA/integration.
• Critical CVEs patched immediately (outside the monthly cycle).
• OpenJDK sync — images track upstream OpenJDK 21 updates shortly after publication.

This yields a runtime that remains current without nightly churn.

---

📦 What’s Inside (and what’s not)

Included — what Java actually needs:

• OpenJDK 21 (JDK + JRE)
• glibc, OpenSSL, trusted CA certificates
• Text rendering libraries (e.g., freetype, harfbuzz)
• POSIX shell and minimal utilities for scripting

Intentionally excluded:

• ❌ No package manager (apt, yum, tdnf)
• ❌ No compilers, headers, or build toolchains
• ❌ No init systems or background daemons

Why no package manager? To keep containers immutable and reproducible. Dependencies are added at build time, scanned, and documented — which reduces *** surface and simplifies audits.

---

🛡 Security & Transparency

Each release passes the same gate:

1. Vulnerability scanning with multiple engines (e.g., grype, trivy).
2. SBOM generation (SPDX + CycloneDX).
3. Hard block on critical CVEs — the image won’t be published until fixed.
4. Reports are embedded in the image at:

/nicesoft/niceos/reports/

Quick peek:

bash
docker run --rm niceos/openjdk21:21.0.9 \
  sh -lc 'ls -1 /nicesoft/niceos/reports && head -n 50 /nicesoft/niceos/reports/index.json'

---

⚙️ Environment Variables & JVM Tuning

The image supports the standard, portable way to configure the JVM via env vars. Below are practical patterns for containers.

Primary variables

• JAVA_TOOL_OPTIONS — the standard, vendor-neutral way to inject JVM flags globally. Example:

  bash
  -e JAVA_TOOL_OPTIONS="-XX:+ExitOnOutOfMemoryError -XX:MaxRAMPercentage=75"
  

• JDK_JAVA_OPTIONS — also respected by modern JDKs; can complement or replace JAVA_TOOL_OPTIONS:

  bash
  -e JDK_JAVA_OPTIONS="-XX:+ExitOnOutOfMemoryError -XX:MaxRAMPercentage=75"
  

Prefer one place for consistency across environments; JAVA_TOOL_OPTIONS is widely used in containers.

NiceOS-specific helpers

• NICEOS_ALLOW_ROOT=1 — opt-in to run as root (discouraged by default).
• NICEOS_WELC_STYLE=emoji|clean — toggle the entrypoint banner style.

Container-aware JVM flags (sane defaults)

• -XX:+UseContainerSupport — container awareness (enabled by default in Java 21).
• -XX:MaxRAMPercentage=50..75 — let the JVM auto-size heaps from cgroups limits.
• -XX:+ExitOnOutOfMemoryError — fail fast on OOM (good for orchestrators).
• -XshowSettings:system — verify container detection and limits on startup.

CPU and memory shaping

• -XX:ActiveProcessorCount=<n> — cap CPU cores the JVM sees (useful when CPU quotas/CPUShares are tricky).
• -XX:InitialRAMPercentage=<p> — faster warmup by avoiding tiny initial heap.
• -XX:MaxRAMPercentage=<p> — cap heap size relative to container memory.
• -XX:MaxMetaspaceSize=<bytes> — bound metaspace to avoid slow leaks.

Examples:

bash
# 512 MiB container: give JVM up to ~75% for heap
docker run --rm -m 512m \
  -e JAVA_TOOL_OPTIONS="-XX:+ExitOnOutOfMemoryError -XX:MaxRAMPercentage=75" \
  niceos/openjdk21:21.0.9_7 java -XshowSettings:vm -version

bash
# Pin JVM to 2 cores, set initial and max heap percentages
-e JAVA_TOOL_OPTIONS="-XX:ActiveProcessorCount=2 -XX:InitialRAMPercentage=15 -XX:MaxRAMPercentage=70"

GC choices

• G1GC is default and balanced for most microservices.

• ZGC (if available in your build) provides low-latency GC for larger heaps:

  bash
  -e JAVA_TOOL_OPTIONS="-XX:+UseZGC -XX:MaxRAMPercentage=70"
  

  Use when latency matters more than absolute throughput.

Diagnostics & stability

• Structured logs:

  bash
  -e JAVA_TOOL_OPTIONS="... -Xlog:gc*:stdout:uptime,tags -Xlog:os*:stdout:time -Xlog:class+load=info"
  

• Exit codes for liveness/readiness:

  bash
  HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD java -version >/dev/null 2>&1 || exit 1
  

Network & proxy

• Standard Docker envs are honored by Java and tools:

  • HTTP_PROXY, HTTPS_PROXY, NO_PROXY

• JVM system properties (when needed):

  • -Dhttp.proxyHost, -Dhttp.proxyPort, etc.

Locale, charset, timezone

• Charset:

  bash
  -e JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"
  

• Timezone:

  bash
  -e JAVA_TOOL_OPTIONS="-Duser.timezone=UTC"
  -e TZ=UTC
  

---

🔧 Customization Examples

Add fonts (PDF/text rendering):

dockerfile
FROM niceos/openjdk21:21.0.9_7
COPY fonts/ /usr/share/fonts/

Global JVM flags baked into the image:

dockerfile
FROM niceos/openjdk21:21.0.9_7
ENV JAVA_TOOL_OPTIONS="-XX:+ExitOnOutOfMemoryError -XX:MaxRAMPercentage=70"

Healthcheck in your runtime image:

dockerfile
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD java -version >/dev/null 2>&1 || exit 1

---

🚀 Usage Patterns

Minimal Dockerfile:

dockerfile
FROM niceos/openjdk21:21.0.9_7
WORKDIR /app
COPY myapp.jar .
CMD ["java", "-jar", "myapp.jar"]

Multi-stage build (Maven example):

dockerfile
# Builder
FROM maven:3-eclipse-temurin AS build
WORKDIR /src
COPY . .
RUN mvn -q -DskipTests package

# Runtime: clean, immutable Java 21 on NiceOS
FROM niceos/openjdk21:21.0.9_7
WORKDIR /app
COPY --from=build /src/target/*.jar /app/app.jar
ENV JAVA_TOOL_OPTIONS="-XX:+ExitOnOutOfMemoryError -XX:MaxRAMPercentage=75"
CMD ["java","-jar","/app/app.jar"]

Run with memory limit:

bash
docker run --rm -m 512m niceos/openjdk21:21.0.9_7 \
  java -XshowSettings:vm -version

---

🧭 Why NiceOS Base (vs Debian/Ubuntu/Alpine)

NiceOS Base is a container-first OS:

• Minimal package set and deterministic layers → fewer surprises.
• No host-style services (systemd, cron, dbus) → smaller *** surface.
• Built-in SBOM + scanner reports → easier compliance and audits.

Compared to general-purpose bases:

• Debian/Ubuntu — broad scope; more packages than a runtime needs.
• Alpine — small, but musl-based; some JVM libraries expect glibc.

NiceOS focuses strictly on runtime correctness: small, secure, predictable.

---

🔐 Certificate Trust & Updates (for this image)

This image does not update system CAs at runtime. System trust stores live under /etc/ssl and /etc/pki and require root to modify. The entrypoint does not call make-ca. Choose one of the supported workflows below.

---

A) Recommended: bake CA updates at build time (root layer)

Do this in your Dockerfile so every container starts fast, immutable, and non-root:

dockerfile
FROM niceos/openjdk21:21.0.9_7

# (optional) corporate anchors; make-ca will merge LOCALDIR into the trust store
# COPY corp-ca/*.pem /etc/ssl/local/

# Build complete PKI: p11-kit anchors, OpenSSL dir/bundles, GNUTLS bundles, Java cacerts
RUN /usr/sbin/make-ca -g --force && \
    touch /var/lib/make-ca/.last_run

Results inside the image (owned by root):

• p11-kit anchors: /etc/pki/anchors/*.p11-kit
• OpenSSL trust directory: /etc/ssl/certs/
• PEM bundles: /etc/pki/tls/certs/ca-bundle.crt, email-ca-bundle.crt, objsign-ca-bundle.crt
• Java truststore (JKS): /etc/pki/tls/java/cacerts
• stamp: /var/lib/make-ca/.last_run

---

B) One-off admin refresh on a host (root)

If you need to refresh the system trust store on a running machine, run the image once as root and exit. This exact command is known-good:

bash
docker run --rm --user 0:0 \
  -e NICEOS_ALLOW_ROOT=1 \
  niceos/openjdk21:latest \
  make-ca -g --force

Notes:

• --user 0:0 runs as root; NICEOS_ALLOW_ROOT=1 lets the entrypoint permit root.
• We invoke make-ca directly so it performs a full rebuild (download + regenerate).
• After this one-off job, run your app containers as non-root as usual.

Quick sanity check:

bash
docker run --rm niceos/openjdk21:21.0.9_7 \
  sh -lc 'ls -l /etc/pki/tls/certs/ca-bundle.crt /etc/pki/tls/java/cacerts 2>/dev/null'

---

C) Non-root runtime: use an app-level trust bundle (no writes to /etc)

When you cannot (or do not want to) modify system paths, stage a complete PKI under a user-writable prefix using DESTDIR and point apps to it.

Stage everything under /opt/pki-overlay (no root needed):

bash
/usr/sbin/make-ca -g --force -D /opt/pki-overlay
# Produces:
# /opt/pki-overlay/etc/ssl/certs/                      (OpenSSL trust dir)
# /opt/pki-overlay/etc/pki/tls/certs/ca-bundle.crt     (PEM bundle)
# /opt/pki-overlay/etc/pki/tls/java/cacerts            (Java JKS)

Wire common tools to the staged bundle:

bash
# OpenSSL / curl / wget
export SSL_CERT_FILE=/opt/pki-overlay/etc/pki/tls/certs/ca-bundle.crt
export CURL_CA_BUNDLE=/opt/pki-overlay/etc/pki/tls/certs/ca-bundle.crt

# Python (requests)
export REQUESTS_CA_BUNDLE=/opt/pki-overlay/etc/pki/tls/certs/ca-bundle.crt

# Git
export GIT_SSL_CAINFO=/opt/pki-overlay/etc/pki/tls/certs/ca-bundle.crt

# Node.js
export NODE_EXTRA_CA_CERTS=/opt/pki-overlay/etc/pki/tls/certs/ca-bundle.crt

Java requires JKS/PKCS12 (not raw PEM):

bash
export JAVA_TOOL_OPTIONS="$JAVA_TOOL_OPTIONS \
  -Djavax.net.ssl.trustStore=/opt/pki-overlay/etc/pki/tls/java/cacerts \
  -Djavax.net.ssl.trustStorePassword=changeit \
  -Djavax.net.ssl.trustStoreType=JKS"

Add/override corporate CAs without root: Put PEMs into the staged LOCALDIR mirror and rebuild:

bash
mkdir -p /opt/pki-overlay/etc/ssl/local
cp corp-ca/*.pem /opt/pki-overlay/etc/ssl/local/
# Rebuild from local + existing certdata
/usr/sbin/make-ca -r -D /opt/pki-overlay

or explicitly point to a custom local dir:

bash
/usr/sbin/make-ca -g --force -D /opt/pki-overlay -l /app/corp-local

---

Update cadence & tips

• Rebuild/bake monthly (or faster on advisories). Root CAs are long-lived, but policy changes happen; leaf certs expire independently.
• Permissions errors like “Permission denied” to /etc/ssl or /etc/pki mean you’re atte***ing a system update without root → use A or B, or switch to C.
• Offline/proxy: provide a saved certdata.txt with -C /path/certdata.txt -f, or use -p/--proxy URI:PORT.

PEM bundle expiry quick check (<60 days):

bash
BUNDLE=/opt/pki-overlay/etc/pki/tls/certs/ca-bundle.crt
awk 'BEGIN{c=0} /-----BEGIN CERTIFICATE-----/{c++} {print > ("/tmp/cert" c ".pem")} /-----END CERTIFICATE-----/{close("/tmp/cert" c ".pem")}' "$BUNDLE"
for f in /tmp/cert*.pem; do
  end=$(openssl x509 -in "$f" -noout -enddate | cut -d= -f2)
  end_ts=$(date -d "$end" +%s); now_ts=$(date +%s)
  left=$(( (end_ts - now_ts) / 86400 ))
  if [ "$left" -lt 60 ]; then
    subj=$(openssl x509 -in "$f" -noout -subject | sed 's/^subject= //')
    printf "%-6s days left | %s\n" "$left" "$subj"
  fi
done
rm -f /tmp/cert*.pem

---

❓ FAQ

Is there a package manager inside the image? No. Images remain immutable. Add dependencies at build time (multi-stage builds recommended).

Can I run as root? Discouraged. Set NICEOS_ALLOW_ROOT=1 only if you must, and review the implications.

Where are the security reports? Inside the image at /nicesoft/niceos/reports/ (includes an index and scanner outputs).

Which architectures are supported? Currently x86_64.

Which tags don’t move? Only pinned build tags like 21.0.9_7. Tags like 21.0.9 and latest can roll forward.

---

📖 Support

---

• Base OS: https://hub.docker.com/r/niceos/base-os

---

License

Copyright © 2025 NiceSOFT LLC

Licensed under the Apache License, Version 2.0 (the “License”). You may obtain a copy at http://www.apache.org/licenses/LICENSE-2.0 Distributed on an “AS IS” basis, without warranties or conditions of any kind.

---

Practical checklist (for happy users)

• Use 21.0.9_7 for production (immutable digest).
• Set JAVA_TOOL_OPTIONS with container-aware flags.
• Apply a healthcheck (java -version) for liveness.
• Add corporate CAs in /etc/ssl/local/ and run make-ca -r.
• Keep images small and auditable: prefer multi-stage builds.