Files
clean-architecture-backend-…/docker-compose.yml
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

114 lines
6.0 KiB
YAML

# =============================================================================
# feature-container-runtime-contract — base docker-compose service definition
#
# Usage:
# docker compose up # base only
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up # dev override
# docker compose -f docker-compose.yml -f docker-compose.local.yml up # local override
#
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
# stop_grace_period : 40s (30s app drain + 5s preStop + 5s safety margin)
#
# Ownership: env-driven-config owns the app shutdown *value* (30s); this contract owns the
# *relationship* (stop_grace_period >= app timeout + preStop + margin). The grace is therefore
# sized UP to the env-keys SSOT value (30s) — you do not shrink the app drain window to fit an
# arbitrary grace. This resolves the earlier 20s/35s drift, which had assumed an app-timeout
# value this branch does not own (env-keys.yaml is the SSOT and sets 30s).
#
# Memory limit (D4):
# The container memory limit MUST be set for -XX:MaxRAMPercentage=75 to be meaningful.
# Default 512m suits a small service; adjust per deployment.
# =============================================================================
services:
app:
build:
context: src/
dockerfile: Dockerfile
args:
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
GIT_SHA: "${GIT_SHA:-0000000}"
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
# qualification: every capability module present, each lane switching on what it tests.
COMPOSITION: "${COMPOSITION:-default}"
# The composition is in the tag, so a lane's qualification image is never reused as the
# default one (Compose reuses a matching tag instead of building).
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
# Generated per run by scripts/run-compose-runtime-smoke.sh and removed on teardown. Seven values
# have no inline default on purpose — the datasource address and credential, the application
# name, and the JWT issuer and audience — so a lane has to supply them, and a lane that borrowed
# the developer's own src/.env would be reproducible only on that developer's machine. Optional,
# so an ordinary `docker compose up` is unaffected.
env_file:
- path: ./src/.env.lane
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
- "9001:9001"
environment:
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# Graceful shutdown — fallback matches the env-keys.yaml SSOT default (30s).
# Override via .env or docker compose --env-file if you need a different value.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# ---- Read-only root filesystem (D2) -------------------------------------
# The application must write only to the tmpfs mounts declared below.
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
read_only: true
tmpfs:
- /tmp:mode=1777,size=128m
- /var/tmp/heap:mode=1777,size=512m
# ---- Fileserver storage volume ------------------------------------------
# A named volume, not a tmpfs and not the read-only root. The Fileserver platform's default
# storage root is /var/lib/backend/files, and with a read-only root and no mount there was
# nowhere on the image it could legally write: enabling the capability failed on its first
# upload rather than at startup. The volume is declared unconditionally because a volume
# nobody writes to costs nothing, while a missing one costs an outage.
#
# Ownership: the image runs as uid/gid 1000 (see src/Dockerfile). Docker initialises a fresh
# named volume from the image path's ownership, so the directory is created in the image with
# that owner; a pre-existing volume or a host bind mount must be chowned to 1000:1000 by the
# operator, or every write is refused with a permission error the application reports as
# STORAGE_UNAVAILABLE.
volumes:
- fileserver-data:/var/lib/backend/files
# ---- Memory limit (D4) --------------------------------------------------
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
mem_limit: 512m
memswap_limit: 512m
# ---- Graceful shutdown (D5) ---------------------------------------------
# stop_grace_period = app drain (30s, env-keys SSOT) + preStop (5s) + margin (5s) = 40s.
stop_grace_period: 40s
# ---- Health check -------------------------------------------------------
# Targets the actuator readiness probe on the management port (9001).
# The warning that used to stand here — that this probe would report UNHEALTHY until two
# parallel branches merged — outlived the branches. src/Dockerfile removed its copy and said
# why: "a stale warning about a healthcheck is the kind of comment that gets a real red
# container ignored."
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:9001/actuator/health/readiness"
interval: 30s
timeout: 5s
start_period: 60s
retries: 3
restart: unless-stopped
volumes:
# Survives container replacement, which is the point: published content outlives the process
# that wrote it. Back this with real storage in any deployment that keeps files.
fileserver-data: