Files
clean-architecture-backend-…/Dockerfile
T
DongHyeonka 23139722e8 fix(compose): heap dump 경로를 컨테이너 메모리 한계 안의 tmpfs에 두지 않는다
문제: 기본 compose.yaml은 -XX:HeapDumpPath=/var/tmp/heap을 512m tmpfs로
붙였다. 컨테이너는 mem_limit 512m·swap 없음이고 힙은 그 75%(384m)다.
tmpfs에 쓴 페이지는 같은 컨테이너 메모리 한계에 잡힌다. 그래서
OutOfMemoryError 때 덤프를 쓰는 동안 컨테이너가 OOM kill(137)될 수 있었고,
runbook이 기대하는 깨끗한 끝(코드 3, ExitOnOutOfMemoryError)이 사라졌다.
덤프가 끝까지 써져도 tmpfs는 컨테이너가 끝나면 함께 사라져 읽을 수 없었다.
Dockerfile 주석은 오케스트레이터에 그 경로를 tmpfs로 붙이라고 했고,
internal-error-spike runbook은 없는 파일 이름(heapdump-<pid>.hprof)을 적었다.

고른 방법:
- 기본 compose.yaml은 그 경로에 아무것도 붙이지 않는다. 루트가 읽기
  전용이라 JVM은 파일을 만들지 못하고 바로 코드 3으로 끝난다. 덤프를 남기는
  dev lane(named volume heap-dumps)은 그대로다.
- scripts/verify-compose-profile-contracts.sh(prCheck의
  verifyComposeProfiles)가 모든 lane에서 그 경로의 tmpfs를 거절한다. 경로는
  Dockerfile의 -XX:HeapDumpPath에서 읽는다.
- Dockerfile 주석과 runbook 둘(runtime-jvm-oom 「진단」, internal-error-spike)에
  덤프를 남기는 법(Kubernetes emptyDir without medium: Memory·PV, dev lane
  volume)과 실제 파일 이름(java_pid<pid>.hprof)을 적었다.
- 버린 대안: 기본 compose에 named volume을 붙이기 — 기본 조립은 디스크에
  아무것도 남기지 않는다는 결정(compose.yaml 「No volume」 주석)과 다르다.
- 고치며 찾은 것(RR9-03-30): ComposeMergeCharacterizationTest는 어느 lane에서도
  돌지 않았다. integrationTest lane은 requires로 적은 클래스 넷만 고른다
  (StrictTestLanePlugin). 그 시험이 보던 기본·dev 조합 렌더링과 계약 스크립트는
  verifyComposeProfiles가 18개 lane으로 이미 본다. 시험과, 그 lane에 compose
  파일을 입력으로 선언하던 블록을 지웠다.

검증(desktop):
- RED: 기준 ca1fbfde + 검사 스크립트만으로 :verifyComposeProfiles 실패
  (기본 compose를 쓰는 lane마다 「heap dump path ... as a tmpfs」).
- 탐침(eclipse-temurin:21-jdk, 읽기 전용 루트, 메모리 192m·swap 없음,
  -Xmx96m으로 OutOfMemoryError):
  경로에 아무것도 없음 → "Unable to create /var/tmp/heap: Read-only file
  system", 코드 3. tmpfs → 덤프를 쓰다 코드 137(OOM kill). 디스크 마운트 →
  덤프 101MB가 남고 코드 3.
- GREEN: :verifyComposeProfiles(18 lane), :app-bootstrap:integrationTest,
  repositoryContractTest, spotlessCheck — 71건 실패 0, skip 1, rc=0.
2026-11-13 03:55:38 +09:00

237 lines
14 KiB
Docker

# syntax=docker/dockerfile:1.7-labs@sha256:b99fecfe00268a8b556fad7d9c37ee25d716ae08a5d7320e6d51c4dd83246894
# =============================================================================
# feature-container-runtime-contract — multi-stage image build
#
# Build requirements:
# docker build -f Dockerfile . -t caskeleton:local \
# --build-arg RELEASE_VERSION=1.2.3 \
# --build-arg BUILD_VERSION=1.2.3+a1b2c3d4e5f6 \
# --build-arg GIT_SHA=a1b2c3d4e5f6 \
# --build-arg SOURCE_URL=https://github.com/your-org/your-repo
# Add --build-arg COMPOSITION=qualification for the Compose-lane image with every capability
# module on the classpath (see the builder stage). The default is the shipped composition.
#
# Design decisions (feature-container-runtime-contract D2/D3/D4):
# D2 — read-only root filesystem: writable mounts must be declared explicitly.
# D3 — non-root user, JRE-only final stage (no full JDK).
# D4 — JVM ergonomics via JAVA_TOOL_OPTIONS and ExitOnOutOfMemoryError.
# =============================================================================
ARG RELEASE_VERSION
ARG BUILD_VERSION
ARG GIT_SHA
ARG SOURCE_URL
# ---- Stage 1: builder -------------------------------------------------------
# Uses the full JDK only in the build stage, never in the final image. Same Ubuntu release as the
# runtime stage below.
FROM eclipse-temurin:21-jdk-noble@sha256:114cabb73033ca4ce7ceec3deb62396bc1b716282bae051ed3c1d82e38fcab2d AS builder
ARG RELEASE_VERSION
ARG GIT_SHA
WORKDIR /build
# Copy the Gradle wrapper and every module's build descriptor + dependency lockfile FIRST,
# so the expensive dependency-resolution layer is cached and only re-runs when a build.gradle
# or gradle.lockfile changes (D8). `--parents` preserves each file's directory structure, so a
# single structure-preserving glob replaces the former per-module COPY list: new modules are
# picked up automatically and this stage never drifts out of sync with settings.gradle again.
# STRICT lock mode still rejects missing/drifted state at verifyDependencyLocks below.
# (Requires the labs Dockerfile frontend — see the `# syntax` directive at the top of this file.)
COPY gradlew ./
COPY gradle/ gradle/
# The repository's Gradle memory, worker and caching settings. Without it the dependency-resolution
# stage below resolves every module's locked configuration on Gradle's defaults rather than the
# -Xmx1g / workers.max / caching-on this build is tuned for.
COPY gradle.properties ./
COPY config/ ./config/
COPY --parents settings.gradle build.gradle **/build.gradle **/gradle.lockfile ./
# The data a leaf's build script reads while Gradle configures it: the JPA leaf's readiness cards
# decide which scenarios each readiness lane requires. Since 2026-11-07 such data lives in the
# release/ folder of the leaf that owns it rather than under config/, and without this line that
# leaf fails to configure in the dependency-resolution stage below.
COPY --parents **/release/*.yaml **/release/*.json ./
# The convention plugins, whole. The glob above copies files named build.gradle and gradle.lockfile,
# which picks up build-logic's own build script and misses the precompiled script plugins beside it —
# so settings.gradle's `includeBuild('build-logic')` resolved against a build that declared no
# plugins and every leaf failed on an unknown plugin id, in the dependency-resolution stage below.
COPY build-logic/ ./build-logic/
# Resolve every module configuration in STRICT mode (no --write-locks in a release build). This
# custom task fails on drift; Gradle's diagnostic `dependencies` report can print FAILED entries
# while still returning exit code 0 and therefore is not a release gate.
RUN test -n "${RELEASE_VERSION}" \
&& test -n "${GIT_SHA}" \
&& ./gradlew verifyDependencyLocks --no-daemon --quiet \
-PreleaseVersion="${RELEASE_VERSION}" -PgitRevision="${GIT_SHA}"
# Copy full source and stage the executable JAR at Gradle's declared Docker output path.
#
# COMPOSITION picks which jar that is. `default` is the composition a service ships (bootJar) and the
# only one a release builds. `qualification` is the same application with every capability module
# on the classpath (qualificationBootJar), for the Compose lanes that turn one on; it is never
# released. Declared here, after the dependency layer, so both share that cache.
ARG COMPOSITION=default
COPY . .
RUN case "${COMPOSITION}" in \
default) ./gradlew :app-bootstrap:stageDockerJar --no-daemon -x test \
-PreleaseVersion="${RELEASE_VERSION}" -PgitRevision="${GIT_SHA}" ;; \
qualification) ./gradlew :app-bootstrap:stageQualificationDockerJar --no-daemon -x test \
-PreleaseVersion="${RELEASE_VERSION}" -PgitRevision="${GIT_SHA}" ;; \
*) echo "COMPOSITION must be default or qualification, got '${COMPOSITION}'" >&2; exit 64 ;; \
esac
# ---- Layer extraction (D8) --------------------------------------------------
# Split the uber JAR into Spring Boot's four layers before it reaches the runtime stage.
#
# Without this the whole fat JAR — every dependency and the application classes in one file — is a
# single image layer, so a release that changes one line of application code re-pushes and re-pulls
# every dependency in the graph. The layers are ordered least- to most-frequently-changed
# (dependencies, loader, snapshot dependencies, application), which is what makes the expensive
# layer cacheable across releases.
#
# `extract` WITHOUT `--launcher` is the layout Spring Boot 4 documents: a thin application JAR whose
# manifest Class-Path points at the extracted lib/ directory, rather than a nested-JAR uber JAR the
# loader has to open and index on every start. It is also the AOT-cache/CDS-friendly layout, which
# is the layout any later startup-time work would need.
#
# Absolute paths on both sides, and no WORKDIR change: DeveloperExperienceContractTest asserts that
# every Dockerfile names the exact Gradle-staged artifact path rather than selecting a JAR, and the
# input here is that same fixed path Gradle wrote. Nothing in this stage may pick a JAR by pattern.
RUN java -Djarmode=tools \
-jar /build/src/bootstrap/app/build/docker/application.jar \
extract --layers --destination /build/src/bootstrap/app/build/docker/extracted
# ---- Stage 2: runtime image -------------------------------------------------
# JRE-only slim image (D3: no full JDK in production image).
# Uses eclipse-temurin:21-jre-noble (Ubuntu 24.04), the Adoptium-supported JRE variant. The release
# scan fails on a High or Critical finding that has a fix (2026-11-11 owner decision), and jammy
# (22.04) carried seven OS findings with a fix (apt, openssl, libbrotli1, ...). When the scan
# reports one again, the fix is a newer digest of this same tag.
FROM eclipse-temurin:21-jre-noble@sha256:0eda5830ed7b669abc246a8dc520ea8a23cab06f9a8d4b6964109e2f2394e46f AS runtime
ARG BUILD_VERSION
ARG GIT_SHA
ARG SOURCE_URL
# OCI image labels (build-arg placeholders — supply at docker build time).
LABEL org.opencontainers.image.title="caskeleton" \
org.opencontainers.image.source="${SOURCE_URL}" \
org.opencontainers.image.revision="${GIT_SHA}" \
org.opencontainers.image.version="${BUILD_VERSION}"
# A release image without source/version metadata is not an artifact this contract permits.
RUN test -n "${BUILD_VERSION}" && test -n "${GIT_SHA}" && test -n "${SOURCE_URL}"
# ---- OS security updates ----------------------------------------------------
# The release scan fails on a High or Critical OS finding that has a fix. The newest Temurin digest
# can lag the Ubuntu security updates: on 2026-11-12 it carried apt 2.8.3, and the scan failed on
# CVE-2026-109518, fixed in 2.8.4ubuntu0.1. The image takes the published updates when it is built
# and drops the package lists again. The digest above stays the starting point; what this adds is
# whatever the archive has fixed since that digest was made.
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get -y --no-install-recommends upgrade \
&& rm -rf /var/lib/apt/lists/*
# ---- Locale / timezone (D4) -------------------------------------------------
# C.UTF-8 is available in eclipse-temurin:21-jre-noble without installing extra packages.
# Do NOT use en_US.UTF-8 — it requires the locales package and may not exist in a slim image.
ENV TZ=UTC \
LANG=C.UTF-8 \
LC_ALL=C.UTF-8
# ---- Writable HOME under read-only root fs (D2) -----------------------------
# The app user is created with --no-create-home and the root filesystem is
# read-only at runtime. Point $HOME at the writable /tmp tmpfs so libraries that
# write under $HOME (e.g. java.util.prefs -> ~/.java/.userPrefs, some SDK caches)
# do not fail with a read-only-filesystem error.
ENV HOME=/tmp
# ---- JVM ergonomics (D4) ----------------------------------------------------
# -XX:MaxRAMPercentage=75 — use up to 75% of the container memory limit for heap.
# -XX:+UseContainerSupport — respect cgroup memory limits (default on JDK 10+, explicit here).
# -XX:+ExitOnOutOfMemoryError — terminate immediately on OOM so the orchestrator can restart.
# -XX:+HeapDumpOnOutOfMemoryError / -XX:HeapDumpPath — write a heap dump to /var/tmp/heap when a
# disk-backed volume is mounted there (see below).
# -Dserver.tomcat.basedir=/tmp — redirect Tomcat temp files to /tmp (D2: read-only root fs).
ENV JAVA_TOOL_OPTIONS="\
-XX:MaxRAMPercentage=75 \
-XX:+UseContainerSupport \
-XX:+ExitOnOutOfMemoryError \
-XX:+HeapDumpOnOutOfMemoryError \
-XX:HeapDumpPath=/var/tmp/heap \
-Dserver.tomcat.basedir=/tmp"
# ---- Filesystem layout (D2: read-only root filesystem) ----------------------
# /tmp — Tomcat working directory (see JAVA_TOOL_OPTIONS above); a tmpfs at runtime.
# /var/tmp/heap — heap dump landing zone. To keep dumps, mount a disk-backed volume there: in
# Kubernetes an emptyDir without `medium: Memory` (it survives a container restart)
# or a PersistentVolume. Never a tmpfs: it is charged to the container's memory
# limit and vanishes on exit, so the dump only risks an OOM kill. With nothing
# mounted the read-only root refuses the file and the JVM exits 3 at once (compose.yaml).
# Both directories are declared here so tooling is aware of them.
RUN mkdir -p /var/tmp/heap && chmod 1777 /var/tmp/heap
# ---- Non-root user (D3) -----------------------------------------------------
# The noble base image ships a login user `ubuntu` with uid and gid 1000, which are the app user's.
# It is removed first, so uid 1000 is this account and nothing else.
RUN userdel --remove ubuntu \
&& groupadd --system --gid 1000 app \
&& useradd --system --uid 1000 --gid app --no-create-home --shell /usr/sbin/nologin app
# No data directory and no VOLUME. The image is the shipped composition, which keeps nothing on
# disk; a selected capability that does brings its mount and that mount's ownership in its own
# Compose overlay, or its orchestrator's volume settings (07-08). A VOLUME here made every
# container, default composition included, create an anonymous volume nobody wrote to.
WORKDIR /app
# ---- Application layers (D8) ------------------------------------------------
# One COPY per Spring Boot layer, ordered least- to most-frequently-changed. Each COPY is its own
# image layer, so a release that only changes application code re-pushes and re-pulls the last one
# instead of the whole dependency graph. This replaced a single `COPY application.jar app.jar`,
# under which every release shipped every dependency again because they lived in the same file as
# the code that changed.
#
# All four land in /app: the extracted application.jar is a thin JAR whose manifest Class-Path
# points at ./lib, which is what the dependencies layer unpacks to.
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/dependencies/ ./
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/spring-boot-loader/ ./
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/snapshot-dependencies/ ./
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/application/ ./
USER app
# ---- Ports ------------------------------------------------------------------
# 8080 — application HTTP port
# 9001 — management / actuator port, from management.server.port in config/observability.yml
EXPOSE 8080 9001
# ---- Health check -----------------------------------------------------------
# Targets the actuator readiness probe on the management port (9001).
#
# The endpoint is real: config/observability.yml sets management.server.port to 9001 and
# management.endpoint.health.probes.enabled to true, which is what publishes
# /actuator/health/readiness. (This block used to carry a note saying the path might 404 because
# the actuator work lived on an unmerged branch. It has been merged for some time, and a stale
# warning about a healthcheck is the kind of comment that gets a real red container ignored.)
#
# A readiness failure here is a correct UNHEALTHY, not a broken probe. In the default composition
# the readiness group is readinessState alone (config/observability.yml); a capability that owns a
# connection adds its own indicator when it is selected — the JPA module adds the datasource — so a
# container started without that dependency reachable is genuinely not ready.
# Kubernetes ignores HEALTHCHECK and uses its own probes against the same path; this exists for
# docker and Compose.
#
# wget is present in eclipse-temurin:21-jre-noble, so nothing is installed for it.
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
CMD wget --no-verbose --tries=1 --spider \
http://localhost:9001/actuator/health/readiness || exit 1
# ---- Entrypoint -------------------------------------------------------------
# The extracted thin JAR, not the uber JAR the builder produced. It carries only application classes
# and a Class-Path pointing at ./lib, so the loader does not open and index a nested-JAR archive on
# every start, and the layout stays AOT-cache/CDS friendly for any later startup work.
ENTRYPOINT ["java", "-jar", "application.jar"]