Files
clean-architecture-backend-…/src/Dockerfile
T
DongHyeonka 5786126cfa fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).

방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.

위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
2026-11-03 19:52:06 +09:00

212 lines
12 KiB
Docker

# syntax=docker/dockerfile:1.7-labs@sha256:b99fecfe00268a8b556fad7d9c37ee25d716ae08a5d7320e6d51c4dd83246894
# =============================================================================
# feature-container-runtime-contract — multi-stage image build
#
# Build requirements:
# docker build -f src/Dockerfile src/ -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.
FROM eclipse-temurin:21-jdk-jammy@sha256:801b7e1a9c4befaf82bf9a2a58025ef43a7694bbc84779187ad0524d84742772 AS builder
ARG RELEASE_VERSION
ARG GIT_SHA
WORKDIR /build/src
# 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 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/app-bootstrap/build/docker/application.jar \
extract --layers --destination /build/src/app-bootstrap/build/docker/extracted
# ---- Stage 2: runtime image -------------------------------------------------
# JRE-only slim image (D3: no full JDK in production image).
# Uses eclipse-temurin:21-jre-jammy — the Adoptium-supported JRE variant.
FROM eclipse-temurin:21-jre-jammy@sha256:199aebeb3adcde4910695cdebfe782ada38dadb6cc8013159b58d3724451befd 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}"
# ---- Locale / timezone (D4) -------------------------------------------------
# C.UTF-8 is available in eclipse-temurin:21-jre-jammy 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 the writable
# /var/tmp/heap mount (see tmpfs mounts in compose files, D2).
# -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) ----------------------
# /var/tmp/heap — heap dump landing zone; must be a writable mount at runtime.
# /tmp — Tomcat working directory (see JAVA_TOOL_OPTIONS above).
# Both directories are declared here so tooling is aware of them; at runtime they
# MUST be mounted as tmpfs (or host volumes) by the orchestrator (see compose files).
RUN mkdir -p /var/tmp/heap && chmod 1777 /var/tmp/heap
# ---- Non-root user (D3) -----------------------------------------------------
RUN 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/app-bootstrap/build/docker/extracted/dependencies/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/spring-boot-loader/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/snapshot-dependencies/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/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-jammy, 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"]