설계: 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>
114 lines
6.0 KiB
YAML
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:
|