Files
DongHyeonka 50cd7154d0 refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
  보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
  .local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
  죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
  겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.

고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
  capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
  고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
  mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
  overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
  계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
  redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
  backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
  전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
  OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
  남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
  런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).

위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
  lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
  src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
  (YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
  둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
  lane-services.yaml(smoke client 변수)은 뺀다.

검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
  :app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
  redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
  :adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
  모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
  all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
  기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
  up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
  README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest, verify-compose rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
2026-11-07 12:52:36 +09:00

105 lines
5.4 KiB
YAML

# =============================================================================
# feature-container-runtime-contract — dev environment override
#
# The off-dev and shared-infra-dev compose lanes merge it onto the development stack:
# docker compose -f compose.yaml -f src/app-bootstrap/compose-lanes/dev.yaml up
#
# It checks that the `dev` deployment profile boots; it is not the development environment, which
# is compose.yaml alone.
#
# Dev intent:
# - Relaxes read-only filesystem (writable, no tmpfs constraint) so developers
# can hot-swap files without image rebuilds.
# - Increases memory allowance for dev/debugging workloads.
# - Disables restart-unless-stopped so crash loops don't mask startup errors.
# - Enables JMX remote port (local only, never in prod).
# - Mounts a local source volume for fast iteration (optional; mount when IDE
# attaches to the running container).
# =============================================================================
services:
app:
# Relax read-only constraint for local development.
read_only: false
# `!override`, not a plain empty list. An empty sequence merges with the base sequence rather
# than replacing it, so the base's /var/tmp/heap tmpfs survived and collided with the bind mount
# below — Compose refuses to have the same target twice and will not silently pick one. That is
# the right refusal: a heap dump written into a tmpfs dies with the container that produced it,
# which is the one moment somebody wants the file.
#
# `!override` needs Compose >= 2.24.4. Whether the collision is actually gone is checked in the
# merged model rather than assumed from this line.
tmpfs: !override []
# More memory for dev profiling / heap dumps.
mem_limit: 1g
memswap_limit: 1g
environment:
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
# environment the application believes it is in, and the two drifting is how a dev stack ends
# up running local's settings.
SPRING_PROFILES_ACTIVE: "dev"
# The datasource address, owned here like compose.yaml and the prod-smoke overlay own theirs. It was
# the only one of the three missing, and the gap was invisible while the qualification wrapper
# supplied a URL to every lane: the dev stack ran on a value that came from the test harness
# rather than from the file that describes the dev environment. With the wrapper no longer
# setting it — it was overriding prod's sslmode=verify-full URL — dev had none at all and
# Flyway was handed the literal string "${APP_DATASOURCE_URL}".
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# Use a shorter drain timeout in dev so restarts are faster.
APP_SERVER_SHUTDOWN_TIMEOUT: "5s"
APP_SERVER_SHUTDOWN: "graceful"
# Remote JMX — bind to localhost only; NEVER expose in production.
JAVA_TOOL_OPTIONS: >-
-XX:MaxRAMPercentage=75
-XX:+UseContainerSupport
-XX:+ExitOnOutOfMemoryError
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/tmp/heap
-Dserver.tomcat.basedir=/tmp
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9999
-Dcom.sun.management.jmxremote.rmi.port=9999
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
-Djava.rmi.server.hostname=127.0.0.1
ports:
- "8080:8080"
- "127.0.0.1:9001:9001" # management — localhost only (07-13)
- "127.0.0.1:9999:9999" # JMX — localhost only
# No health check constraint in dev; let the app start at its own pace.
healthcheck:
disable: true
# Do not restart automatically so crash loops stay visible.
restart: "no"
# Optional: mount heap dump directory to host for dev analysis.
# The base declares /var/tmp/heap as a tmpfs, which is right for an ephemeral runtime and wrong
# for dev: a heap dump written into a tmpfs dies with the container that produced it, which is
# the one moment somebody wants the file. Compose refuses to have both, and correctly — it will
# not silently pick one — so the tmpfs list is replaced rather than appended to.
#
# `!override` needs Compose >= 2.24.4. An empty sequence is not assumed to delete the base
# sequence by itself; scripts/verify-compose-profile-contracts.sh checks mount-target uniqueness
# in the merged model, which is what actually proves the collision is gone.
volumes:
- type: bind
source: ./tmp/heap-dumps
target: /var/tmp/heap
bind:
create_host_path: true
# The same network the shared infrastructure lives on. The local stack (now compose.yaml) joins it and the dev
# overlay did not, so a dev lane that started PostgreSQL beside the application put the two on
# different networks: `UnknownHostException: db`, from a container that was running and healthy
# a metre away. Compose puts a service with no `networks:` on `default`, which is a network of
# its own making — so the omission reads as a working stack until something has to resolve a
# name across it.
networks:
- caskeleton-infra
networks:
# Defined in compose.yaml, where the services that share it live.
caskeleton-infra:
external: false