Files
clean-architecture-backend-…/src
DongHyeonka 8ebe98e69a fix(migration): 실패한 DROP INDEX CONCURRENTLY를 runbook 절차로 복구되게 한다
문제 (재리뷰 round8 RR8-03-01)
- migration-failed.md "Recover a failed concurrent index migration"은
  CREATE·DROP·REINDEX 동시 문장 셋을 대상으로 두고, 2단계에서 "빌드가 남긴
  무효 인덱스를 지운다"고 한다. 실패한 DROP INDEX CONCURRENTLY가 남긴 무효
  인덱스는 그 마이그레이션이 지우려던 인덱스다. 절차대로 지우고 실패 행을
  지운 뒤 다시 배포하면 같은 문장이 42704(index does not exist)로 실패하고
  실패 행이 다시 생긴다. 운영자는 처음과 같은 막힌 상태로 돌아간다.
- 고치다 같은 절에서 하나 더 찾았다. 2단계(DROP INDEX CONCURRENTLY)가
  3단계(원인 정리) 앞이다. 취소·timeout이 원인이면 그 열린 트랜잭션이
  운영자의 DROP INDEX CONCURRENTLY도 붙잡아, 2단계가 3단계를 기다린다.
- runbook을 실행하는 IT는 중복으로 실패한 unique CREATE 한 경우만 돌렸다.

고른 방법
- 리뷰 권장안: 무효 인덱스를 지우는 단계를 문장 종류로 나눈다. CREATE는
  그 인덱스를, REINDEX는 _ccnew(또는 _ccold) 사본을 지운다. DROP INDEX
  CONCURRENTLY면 이 단계를 건너뛴다. 다시 배포한 같은 문장이 그 인덱스를
  지운다(PostgreSQL은 중간에 실패한 DROP INDEX CONCURRENTLY의 재시도를
  받는다). 5단계 문장도 "builds the index"에서 세 경우로 고친다.
- 단계 순서를 "빌드 확인 → 원인 정리 → 무효 인덱스 삭제 → 실패 행 삭제 →
  재배포"로 바꾼다. 실패 행만 지운다는 소유자 결정(2026-11-06)은 그대로다.
- IT에 두 경우를 더한다. 열린 쓰기를 기다리다 취소된 REINDEX와 열린
  읽기를 기다리다 취소된 DROP에 runbook SQL을 runbook에서 읽어 돌리고,
  재배포 뒤 이력 [1 true, 2 true], 무효 인덱스 없음, V1 checksum 그대로를
  단언한다. 대기를 30초 기다리지 않고, 문장이 잠금을 기다리는 것을 본
  즉시 취소하는 도우미(cancelledOnceItWaits)를 둔다.
- 같은 절차를 요약한 곳을 같이 고친다: docs/jpa/runbooks.md "An invalid
  index exists", migration-guide "Concurrent index builds"(DROP이 무엇을
  기다리는지 포함), 학습 문서 8.2절, ConcurrentIndexMigrationInspector의
  Javadoc과 실패 메시지, 업그레이드 안내 5절 행(그 범위가 아직 main에
  없어 행을 최종 동작으로 고치고 머리 목록에 더함).
- 버린 대안: 가이드와 검사기가 DROP INDEX CONCURRENTLY에 IF EXISTS를
  요구한다. 이미 배포된 파일은 고칠 수 없어 새 파일에만 통하고, 서비스의
  기존 마이그레이션 검사를 새로 실패시킨다.

위험·한계
- 운영자가 실패한 문장의 종류를 마이그레이션 파일에서 읽어야 한다.
  runbook이 이력 행만으로는 알 수 없는 것을 요구한다.
- REINDEX가 swap 뒤에 실패해 _ccold가 남는 경우는 문서로만 다뤘다(실행
  재현 없음). PostgreSQL 문서의 권장 복구와 같다.
- 단계 번호가 바뀌었다. 리뷰 기록이 옛 번호(2단계 = drop)로 적은 곳은 그때의
  기록이라 두었다.

RED (desktop, 기준 3eb3b067 + 임시 테스트, 로그 ~/r9-g3-logs/red-concurrent.log)
- postgresqlConcurrentIndexMigrationIntegrationTest rc=1, 9건 중 2건 실패
  - redAFailedConcurrentDropIsRecoveredByTheBaseRunbook: 기준 runbook
    1·2·4단계 뒤 재배포가 "42704 ERROR: index "ix_probe_id" does not
    exist"로 실패, 이력 [1 true, 2 false] 그대로
  - redTheBaseRunbookDropsBeforeItEndsTheTransaction: 기준 순서의 2단계
    (_ccnew drop)가 열린 쓰기 트랜잭션을 기다려 취소됨
  - 나머지 7건(기존) 통과

검증 (desktop, 이 커밋의 트리 7cfaa83c, --no-build-cache, 로그 ~/r9-g3-logs/)
- :adapter:outbound:persistence-jpa:check rc=0, test 666건 실패·skip 0
- postgresqlConcurrentIndexMigrationIntegrationTest rc=0, 9건(새 2건 포함)
- :adapter:outbound:persistence-jpa:testQualityCheck rc=0
- :app-bootstrap:documentContractTest rc=0, 67건(RunbookCoverageContractTest
  포함)
- -p optional-platforms :grpc:grpc-operation-ledger-jpa:integrationTest
  rc=0, 47건(검사기 사본이 바뀌어서)
- FROM-CACHE 0
- 상대 링크(노트북): python3 scripts/check-work-docs.py --links로 바꾼
  문서 5개(migration-failed.md, jpa/runbooks.md, migration-guide.md,
  학습 문서, 업그레이드 안내) rc=0, 깨진 링크 0

Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-01
Fixes: 6ec0c4f7fa ("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다")
2026-11-07 08:07:42 +09:00
..

src — 빌드 스크립트 / 환경 변수 참조

src/ 는 Gradle 멀티모듈 루트입니다. 모듈 경계·의존 방향 규칙은 루트 CLAUDE.md 와 AGENTS.md, 모듈별 규칙은 각 모듈의 CLAUDE.md 가 SSOT 입니다.

이 문서는 build.gradle 과 .env.example(복사해 .env 로 씀) 의 코드 주석에서 덜어낸 설정 항목 설명과 결정 근거를 모아둔 참조용 기록입니다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조" 포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명합니다.


build.gradle — 빌드 / 검증 게이트

검증은 로컬 피드백과 저장소 전체 검증을 분리합니다. :<leaf>:check는 해당 모듈의 컴파일, 테스트, Spotless, Checkstyle, Error Prone만 담당합니다. 저장소 전체 정책은 이름이 드러나는 루트 task로 실행하며, CI가 이를 집계합니다.

이 셋의 역할은 겹치지 않습니다. Spotless(google-java-format)가 포맷과 import 순서를 소유하고, Checkstyle은 포매터가 표현할 수 없는 것만 — 네이밍과 몇 가지 논리/설계 규칙만 — 봅니다 (config/checkstyle/checkstyle.xml). 줄 길이·들여쓰기·import 순서 모듈이 여기에 없는 것은 누락이 아니라 포매터와 싸우지 않기 위한 선택입니다. Error Prone은 컴파일 시점 버그 패턴을 담당합니다.

게이트 하는 일
architectureCheck Clean Architecture 의존 방향, domain-core·shared-contract·application-* 순수성, Git에 실리지 않는 source package, ArchUnit을 검사
qualityCheck 모든 leaf의 SpotBugs + FindSecBugs를 실행
configContractCheck :app-bootstrap:verifyEnvKeys로 환경 설정 계약을 검사
qualificationCheck 전체 기동(system) 레인과 보조 source set Checkstyle을 실행
integrationCheck 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: -Predis.topology.mode, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력
performanceCheck 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(-Pperformance.assertions.enabled가 true가 아니면 실패, skip된 테스트가 있어도 실패). integration-main.yml performance-check가 main·nightly에 같은 명령으로 돌림
verifyStrictLaneStages --dry-run 전용. explicitOnly가 아닌 strict lane이 workflow가 실제 실행하는 단계(ci·:sample-portfolio:check·mainCheck·integrationCheck·performanceCheck·releaseCheck) 중 하나의 계획에 있는지, 각 단계를 workflow가 --dry-run 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(--dry-run·-v·--help 등)과, 실패해도 단계가 실패하지 않을 수 있거나(|| true, pipefail 없는 파이프, if 조건 등) 돌지 않을 수 있거나(조건부 exit 0 뒤, 요청으로만 시작하는 workflow, paths 필터로만 시작하는 workflow, releaseCheck 밖의 단계를 태그 push·release로만 시작하는 workflow 등) 검사가 읽지 않는(|| exit 1, { } 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 build-logic/README.md. PR 게이트가 돌림
ci PR 게이트: 모든 leaf check(API surface 검사 포함, 소유자 결정 20) + architectureCheck + qualityCheck
mainCheck main 단계: configContractCheck + qualificationCheck + sample web 계약 + sample 전체 기동(:sample-portfolio:systemTest) + verifyPublicPathSnapshot + 전송·메시징 qualification 레인 + 각 leaf의 mainCheck(문서 대조 레인 *DocumentContractTest, objectstorage MinIO 레인)
releaseCheck tag 전용 검사: verifyReleaseProvenance + verifyPublicPathSnapshot(ci를 다시 돌리지 않음)

따라서 로컬에서 한 모듈만 수정했다면 ./gradlew :domain-core:check처럼 focused task를 먼저 사용합니다. 전체 기동 qualification은 일반 leaf check나 :app-bootstrap:build에 매달지 않고 qualificationCheck/mainCheck에서 실행합니다.

2026-09에 삭제한 게이트. verifyOneTypePerFile(Checkstyle의 OneTopLevelClass가 같은 규칙을 파싱된 파일에 대해 검사한다), verifyTrivyignore·verifyQuarantineSunset(빈 레지스트리를 지키는 수백 줄짜리 커스텀 YAML 파서), verifyReadmeCommands·verifyDocumentedLeafCount· verifyRunbookReferences·verifyTestSourceSetRegistry(문서 파서), verifyConfigurationPropertiesProcessor(ca.spring-config convention plugin이 대체). 근거는 docs/superpowers/specs/2026-09-16-verification-surface-reduction-design.md.

Local bootstrap

scripts/bootstrap-local.sh [profile](저장소 루트)은 compile → Docker 확인 → DB 기동 대기 → app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 ./gradlew bootstrap, 리뷰 BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김). DB와 app lifecycle은 저장소 루트의 base/local Compose 조합이 소유하며, app startup Flyway가 끝나 public health endpoint가 준비되어야 다음 단계로 넘어갑니다. src/.env.example은 커밋된 env 계약이고 src/.env는 로컬 실행 입력입니다. verifyEnvKeys는 example/registry/shipped YAML을 함께 검사합니다.

Traceable version + dependency locking

  • leaf version은 release version뿐입니다(-PreleaseVersion/RELEASE_VERSION, 기본 0.0.1). revision(-PgitRevision/GIT_SHA/GITHUB_SHA)을 모르면 -SNAPSHOT이 붙습니다. revision은 jar 이름에 넣지 않고 각 jar manifest의 Build-Revision과 app-bootstrap의 META-INF/build-info.properties(build.revision)에 남깁니다. 예전에는 version이 <MAJOR>.<MINOR>.<PATCH>+<sha>라 커밋마다 새 jar 이름이 생겼고 그 잔여물을 ca.archive-hygiene이 치웠는데, 둘 다 없앴습니다(리뷰 BUILD-O3-5).
  • releaseCheck가 실행하는 verifyReleaseProvenance(루트 build.gradle, revision 판정은 ca.java-conventions와 같은 함수)는 source revision이 없으면 실패하므로 추적 불가능한 산출물을 release로 취급할 수 없습니다. 예전 ca.release-provenance 플러그인은 없앴습니다(리뷰 BUILD-O3-5).
  • 모든 subproject가 lockAllConfigurations() + LockMode.STRICT를 사용하고, lock state는 Gradle 기본 <module>/gradle.lockfile에 둡니다. 이 경로는 Renovate Gradle manager 기본 인식 경로와 같습니다.
  • lock 갱신은 ./gradlew resolveAndLockAll --write-locks 한 가지 명령으로 수행합니다. 이 task는 --write-locks가 없으면 실패하며, 일반 build가 lock state를 조용히 다시 쓰지 못하게 합니다.

Reproducible archives (D10)

모든 AbstractArchiveTask는 file timestamp 보존을 끄고, file order를 재현 가능하게 정렬하며, directory/file mode를 각각 0755/0644로 고정합니다. Java toolchain은 21이고 로컬·CI patch version은 root .tool-versions의 Temurin 값으로 맞춥니다.

archive task 자체는 timestamp 비보존·재현 가능한 file order·고정 mode를 강제합니다. 현재 저장소에는 별도의 verify-reproducible-build.sh가 없으므로 byte-for-byte 이중-build 비교를 자동 게이트라고 주장하지 않습니다. 릴리스 검증의 정본 진입점은 ./gradlew releaseCheck와 .github/workflows/release.yml입니다.

-parameters 컴파일러 플래그

  • 결정. 모든 subproject 의 Java 컴파일에 -parameters 플래그를 직접 설정합니다.
  • 근거. Spring MVC 는 @PathVariable / @RequestParam 의 이름을 reflection 의 parameter metadata 에서 읽습니다. 이 플래그가 없으면 파라미터 이름이 arg0, arg1 로 컴파일되어 바인딩이 깨집니다. Spring Boot Gradle 플러그인은 이 플래그를 자동으로 켜 주지만, 이 프로젝트는 플러그인을 apply false 로 두기 때문에 자동 적용이 일어나지 않습니다. 그래서 각 subproject 의 JavaCompile 에 직접 설정합니다.

verifyCleanArchitectureDependencies

  • 하는 일. config/architecture/modules.json의 allowed_dependencies를 읽고, 실제 Gradle 프로젝트 의존(api / implementation / compileOnly / runtimeOnly)이 그 범위를 벗어나면 빌드를 실패시킵니다.
  • JSON registry가 의존 방향의 SSOT 입니다. 새 모듈이나 새 production 의존 edge를 추가하면 registry와 :app-bootstrap:architectureTest의 관련 ArchUnit 규칙을 함께 갱신해야 합니다. settings와 gate는 같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부합니다.

조립 루트가 받는 모듈의 별도 membership 검사는 없습니다. app-bootstrap의 allowed_dependencies 밖의 모듈은 방향 게이트가 막고, 무엇이 실제로 실리는지는 app-bootstrap/build.gradle의 의존성이 정합니다.

세 opt-in inbound transport의 test-only composition, 실제 wire 경계, positive-count/zero-skip 증거는 다음 release-blocking aggregate로 실행합니다.

./gradlew conditionalTransportQualification

파일당 public 최상위 타입 1개 (code-conventions I6)

Checkstyle이 소유합니다 — OneTopLevelClass와 OuterTypeFilename(config/checkstyle/checkstyle.xml). 각 leaf의 checkstyleMain/checkstyleTest가 그 leaf의 check에서 돕니다.

verifyOneTypePerFile이라는 루트 태스크가 있었고 삭제했습니다. src/main/java를 줄 단위 정규식으로 읽었고 세 가지가 틀렸습니다: package-private 최상위 타입이 보이지 않았고(126개 main 소스가 한 번도 매칭되지 않아, 파일 하나에 package-private 타입 다섯 개가 있어도 통과했다), src/main/java만 읽었고, ^public 앵커 때문에 블록 주석이나 텍스트 블록의 public으로 시작하는 줄을 선언으로 셌습니다. Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돕니다.

:app-bootstrap:verifyEnvKeys

  • 소유. app-bootstrap. 이 질문("이 애플리케이션의 배포에 무엇을 줘야 하는가")은 composition root의 것이고, ./gradlew :domain-core:check가 알아야 할 사항이 아닙니다. 루트 집계 이름은 configContractCheck이고 구현은 build-logic의 ca.config-contract plugin입니다(소유자 결정 4: 태스크는 app-bootstrap에 유지, build-tools included build는 비워서 삭제).
  • 하는 일. docs/registries/env-keys.yaml, app-bootstrap의 application*.yml + config/*.yml, capability 모듈이 싣는 config/*.yml·config/module-defaults/*.yml(기본 조립에 없어도 검사한다), src/.env.example을 lock-step(서로 어긋나지 않게) 으로 유지합니다. env-keys.yaml 이 APP_ 키의 SSOT 이고, drift 가 생기면 빌드를 실패시킵니다.
  • 막으려는 것 3가지. (1) 필수 env 가 조용히 누락되는 것, (2) 더 이상 쓰지 않는 stale env 키가 .env.example 에 남는 것, (3) 실제로 쓰는 APP_ 키가 registry 에 등록되지 않고 빠져나가는 것.
  • 검사 항목.
    • A. application.yml 의 placeholder 중 inline default(${VAR:default})가 없는 필수 placeholder(${VAR})는 반드시 .env.example 에 존재해야 합니다.
    • B. .env.example 의 모든 키는 shipped configuration의 어떤 ${...} placeholder 또는 등록된 consumer가 참조해야 합니다. (아무도 안 쓰는 키는 orphan 으로 간주해 실패)
    • C. .env.example 의 모든 APP_ 키는 registry 에 - name: <KEY> 행이 있어야 합니다.
  • SPRING_* 키는 왜 registry 추적 대상이 아닌가. SPRING_* 는 Spring Boot 가 정의한 native 키라 프로젝트가 소유한 계약이 아닙니다. 그래서 C 검사는 일부러 APP_ prefix 로만 범위를 좁혔습니다.
  • 비고. src/.env.example이 커밋된 환경 계약이고 src/.env는 로컬 실행용 입력입니다.

verifyPublicPathSnapshot

  • 하는 일. deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킵니다.
  • 배경. 이 앱은 deny-by-default 입니다. 즉 SECURITY_PUBLIC_PATHS 가 먹이는 명시적 permitAll() 경로를 제외한 모든 요청은 인증을 요구합니다 (app-bootstrap/src/main/resources/config/security.yml → SecuritySettings.publicPaths() → SecurityConfig). 설정 분할 이전에는 이 SSOT 가 src/.env 였고 문서만 그대로 남아 있었습니다. 스냅샷 플러그인이 실제로 읽는 파일은 config/security.yml 입니다 (build-logic/.../publicpath/PublicPathSnapshotPlugin.java). 이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점입니다. 그래서 그 표면을 snapshot 으로 떠 두고, 미승인 변경에 빌드를 실패시킵니다.
  • 승인 방법. verifyPublicPathSnapshot 은 항상 읽기 전용입니다. reviewer 가 변경을 승인한 뒤 ./gradlew updatePublicPathSnapshot -PapprovePublicPathChange 로 snapshot 을 명시적으로 다시 생성합니다. 공개 경로 변경은 보안 리뷰 대상으로 보고 재생성된 snapshot 을 함께 커밋합니다.
  • 결정 — 무엇을 snapshot 했나 (프로젝트 선택). 초기안은 기동 시 SecurityFilterChain.getFilters() 를 introspection 하는 방식이었습니다. 하지만 그 reflection 은 Spring 버전마다 깨지기 쉽습니다(permitAll matcher 가 RequestMatcherDelegatingAuthorizationManager 의 private 필드에 숨어 있음). 그래서 permitAll() 을 실제로 먹이는 결정적 SSOT 인 SECURITY_PUBLIC_PATHS 자체를 snapshot 합니다. 탐지 목표(공개 경로 변경은 무조건 게이트를 실패시킨다)는 같고, 메커니즘은 더 견고합니다.
  • snapshot 위치. docs/security/public-paths-snapshot.txt. 이 파일은 커밋된 필수 보안 baseline 입니다. CI 는 Gradle 실행 전에 파일이 비어 있지 않고 Git에 추적되는지 검사하므로 fresh checkout 에서 누락되거나 untracked 상태면 즉시 실패합니다. 승인된 변경만 update task로 재생성한 뒤 보안 리뷰와 함께 커밋합니다.

Trivy suppression과 플래키 격리 — 정책은 유지, 파서는 삭제

Trivy suppression. repo 루트 .trivyignore.yaml이 유일한 suppression 소스이고, 모든 Trivy 호출이 --ignorefile .trivyignore.yaml로 명시합니다. 항목은 id, 비어 있지 않은 statement, 90일 이내의 미래 expired_at을 갖춰야 합니다. 이 규칙은 그대로이고, 강제하는 주체가 .github/CODEOWNERS 리뷰어로 바뀌었습니다. verifyTrivyignore는 105줄짜리 손으로 쓴 YAML 파서였고 — 들여쓰기 추적, 인라인 스칼라 처리, 따옴표 제거 — 지키던 파일은 만들어진 이래 계속 비어 있었습니다. 실제 항목이 생기고 그것이 drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 진짜 YAML 라이브러리로.

플래키 격리. quarantineTest 버킷과 CI의 비차단 quarantine 잡은 삭제했습니다. 격리된 테스트가 한 번도 없었습니다. 간헐 실패 테스트는 고치거나 지웁니다.

flaky-quarantine.yaml 레지스트리와 verifyQuarantineSunset(14일 sunset + drift 검사)은 삭제했습니다. 250줄짜리 YAML 파서 + Java 렉서(주석과 문자열 리터럴 안의 @Tag("quarantine")를 걸러내려고 인덱스 보존 렉서를 직접 구현)로 항목이 0개인 레지스트리를 지키고 있었습니다. 순서가 반대입니다 — 실제로 격리된 테스트가 생기고, 그게 주차장이 되기 시작할 때 도입할 정책입니다.

CI 게이트 배선

  • 소유 범위. 이 계약은 게이트 배선(어떤 게이트가 CI 에서 돌고 실패 시 어떻게 릴리스를 막는가)을 소유합니다. 개별 scanner/tool/severity 정책 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체입니다.

    .github/ci-gate-matrix.yml(1,025줄, 107개 게이트 행)과 .github/scripts/verify-gate-matrix.sh (568줄)는 삭제했습니다. 그 표는 이미 두 그래프에 있는 정보의 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했습니다. 결과적으로 체크 하나를 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했습니다.

  • 워크플로. .github/workflows/ci-quality-gates.yml 의 release-gate 잡이 모든 release-blocking 게이트의 fan-in(단일 required status check)입니다. included build 테스트는 경로 필터가 걸린 build-logic.yml이, main 단계(mainCheck)·configuration-cache·JPA candidate evidence는 integration-main.yml이 돌립니다. 위임 게이트(Trivy SCA/이미지 스캔)는 dependency-vulnerability.yml 가 소유하며, GitHub Actions 는 워크플로 간 needs 를 못 쓰므로 branch protection 의 required check 합집합으로 묶습니다.


.env — 환경 변수 레퍼런스

spring-dotenv 가 src/.env 를 읽어 외부화 설정을 주입합니다(bootRun 의 working dir 가 src/ 라 이 파일이 잡힙니다). 아래는 섹션별 키 설명입니다. 따로 표기가 없으면 restart-only(값 변경 시 재기동 필요)로 간주하세요.

App identity

  • APP_NAME — spring.application.name 과 JSON 로그의 app 필드. 자유 문자열.
  • SPRING_PROFILES_ACTIVE — 활성 Spring profile. 보통 local | dev | stage | prod. JSON 로그의 profile 필드도 이 값을 씁니다.

Runtime safety (기동 시 fail-fast 검사, D8)

  • APP_SERVER_ERROR_INCLUDE_STACKTRACE / APP_SERVER_ERROR_INCLUDE_MESSAGE — 로컬 디버깅용. prod에서 never가 아니면 ErrorDetailExposureSafetyValidator가 기동을 막습니다(exit 71, spring.web.error.include-binding-errors·include-exception도 같음). request logging은 body를 읽지 않는 계약을 검증합니다.
  • APP_MULTI_INSTANCE_ENABLED — true 면 cross-instance DistributedLockPort (distributedLockProvider)가 조립돼 있어야 하며, 없으면 기동이 실패합니다(exit 72, StartupSafetyValidator).
  • APP_RATE_LIMIT_ENABLED — provider-neutral edge rate-limit interceptor 활성화 (429 + Retry-After + X-RateLimit-* 응답). 기본값은 false이며, true로 바꿀 때는 APP_RATE_LIMIT_PROVIDER=redis와 canonical coordination role을 함께 구성해야 합니다. 비인증 요청의 키는 getRemoteAddr() 입니다. 프록시 뒤라면 APP_SERVER_FORWARD_HEADERS_STRATEGY=native 와 server.tomcat.remoteip.internal-proxies 로 신뢰할 프록시를 지정하세요(framework 면 rate limit 이 기동을 거부합니다).
  • APP_IDEMPOTENCY_PROVIDER — 요청 멱등성 store. disabled(기본) | redis | postgresql. postgresql 은 PostgreSQL data source 가 아니면 기동을 거부하므로 bootRunH2 에서는 disabled 나 redis 를 씁니다.
  • APP_IDEMPOTENCY_TTL — 완료 응답을 재생할 수 있는 기간(replay-ttl). duration(예: 24h). 최대 72h 이고 넘으면 기동을 거부합니다. (D6) APP_IDEMPOTENCY_PROCESSING_LEASE(기본 30s)보다 짧아도, APP_IDEMPOTENCY_FAILURE_RETENTION(기본 24h)보다 길어도 기동을 거부합니다. 24h보다 올리려면 APP_IDEMPOTENCY_FAILURE_RETENTION도 함께 올립니다.

Async executor

@Async ThreadPoolTaskExecutor 풀 크기 설정입니다.

  • APP_ASYNC_EXECUTOR_CORE_SIZE — 항상 살아있는 워커 수. 1 이상 정수.
  • APP_ASYNC_EXECUTOR_MAX_SIZE — 워커 수 상한. core-size 이상.
  • APP_ASYNC_EXECUTOR_QUEUE_CAPACITY — 백로그 큐 용량. bounded(유한) 필수, unbounded 금지(D7). 1 이상 정수.

기능 추가 = 한 줄 + env

기본 조립(bootJar)에는 web, 관측(actuator·metrics·tracing·로그), domain-core·application-core· shared-contract, adapter:outbound:support·adapter:outbound:identifier만 들어 있습니다. DB·Redis· Kafka 없이 기동합니다. 나머지 기능은 app-bootstrap/build.gradle에 주석 처리된 runtimeOnly 한 줄로 있습니다.

  • 켜기: 그 줄의 주석을 풀고, 아래 env를 src/.env에 넣습니다. 모듈이 classpath에 있으면 켜집니다.
  • 끄기: 줄을 지웁니다. 모듈의 bean·설정·의존성이 함께 빠집니다. 줄은 두고 잠시 끄려면 "끄는 키"를 false로 줍니다(모든 키의 기본값은 true).
  • 줄을 바꾼 뒤: strict lock을 갱신합니다. ./gradlew :app-bootstrap:resolveAndLockAll --write-locks
  • 모든 capability를 한 번에 싣는 jar가 필요하면(compose 레인·CI) ./gradlew :app-bootstrap:qualificationBootJar를 씁니다. 배포용이 아닙니다.
capability build.gradle 한 줄 켜진 뒤 필요한 env 끄는 키
JPA/PostgreSQL (Flyway·outbox store·JDBC 멱등성·분산 락) runtimeOnly project(':adapter:outbound:persistence-jpa') APP_DATASOURCE_URL, APP_DATASOURCE_USERNAME, APP_DATASOURCE_PASSWORD APP_PERSISTENCE_JPA_ENABLED
Redis (cache·rate limit·lease·멱등성) runtimeOnly project(':adapter:outbound:cache-redis') APP_REDIS_MODE, APP_REDIS_NODES, APP_REDIS_NAMESPACE_*, APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE, 쓰는 역할의 선택자(APP_CACHE_CANONICAL_DEFAULT_PROVIDER, APP_RATE_LIMIT_PROVIDER, APP_LEASE_PROVIDER, APP_IDEMPOTENCY_PROVIDER=redis) APP_REDIS_ENABLED
Kafka 발행 runtimeOnly project(':adapter:outbound:messaging-kafka') APP_MESSAGING_KAFKA_BROKERS, APP_MESSAGING_PRODUCER_ID APP_MESSAGING_ENABLED
Mongo runtimeOnly project(':adapter:outbound:persistence-mongo') APP_PERSISTENCE_MONGO_ACTIVE_PROFILE, SPRING_MONGODB_URI(또는 profile의 uri-secret) APP_PERSISTENCE_MONGO_ENABLED
GraphQL runtimeOnly project(':adapter:inbound:graphql') APP_GRAPHQL_DEPLOYMENT_MODE (local→LOCAL, dev→DEV, prod→PRODUCTION_*) APP_GRAPHQL_ENABLED
외부 HTTP 호출 runtimeOnly project(':adapter:outbound:httpclient') client 하나 이상: APP_HTTPCLIENT_CLIENTS_0_* (docs/httpclient/env-fields.yaml) APP_HTTPCLIENT_ENABLED
객체 저장소 (S3/로컬) runtimeOnly project(':adapter:outbound:objectstorage') 전용 env 없음. app.object-storage.*의 provider·destination을 application-*.yml에 적음 app.object-storage.enabled
WebSocket (STOMP push) runtimeOnly project(':adapter:inbound:websocket') 없음(기본값으로 동작). origin은 APP_WEBSOCKET_ALLOWED_ORIGINS APP_WEBSOCKET_ENABLED
gRPC 서버 runtimeOnly project(':adapter:inbound:grpc') APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true (지금 받는 listener가 loopback plaintext뿐) app.grpc.server.enabled
파일 서버 (JPA를 함께 가져옴) runtimeOnly project(':composition:fileserver-platform') APP_FILESERVER_PLATFORM_STORAGE_ROOT, APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY, 그리고 FileAccessPolicyPort bean 또는 APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=role-based APP_FILESERVER_PLATFORM_ENABLED
알림 (SMTP/SES, JPA 줄도 필요) runtimeOnly project(':composition:notification-platform') 키 8종과 각 _ID(APP_NOTIFICATION_PLATFORM_*_KEY, *_KEY_ID), 쓰는 provider 설정(APP_NOTIFICATION_PLATFORM_SMTP_* 또는 _SES_*) APP_NOTIFICATION_PLATFORM_ENABLED

전체 목록과 타입·기본값은 docs/registries/env-keys.yaml, 각 모듈이 제공하는 것은 그 모듈 README의 "제공하는 것 · 추가할 한 줄 · env 키" 절에 있습니다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay → JPA + Kafka)은 설정 검사가 아니라 build 줄로 맞춥니다. 표에 "JPA 줄도 필요"라고 적힌 기능은 두 줄을 함께 넣습니다.

어떤 자동 설정이 켜졌는지는 Spring Boot의 conditions endpoint로 봅니다. 기본 노출 목록에는 없으므로 필요할 때 management.endpoints.web.exposure.include에 추가합니다.

종속 선택자 둘:

  • APP_GRAPHQL_DEPLOYMENT_MODE — GraphQL이 켜지면 필수���고 기본값이 없습니다. 예전의 boolean과 enum 두 기본값이 서로 다른 말을 했기 때문에, 안전 태세는 배포가 명시적으로 고릅니다. 허용되는 값은 런타임 환경(local/dev/prod)마다 다릅니다.
  • APP_NOTIFICATION_PLATFORM_MODE — SERVING(기본) 또는 INGEST_ONLY. 선택 사항이고, 허용 값은 NotificationModeSsotTest가 enum에서 파생합니다.

Compose와 런타임 스모크

  • Docker Compose 최소 버전 2.24.4. SSOT는 src/config/runtime/compose-profile-contracts.json 이고, 정본 스크립트가 검증합니다.
  • 진입점은 둘뿐이고, 그 둘만이 증거입니다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이 초록으로 보고됩니다.
# 정적: profile별 정확한 service set, 병합된 모델 전체, mount target 유일성
./scripts/verify-compose-profile-contracts.sh

# 동적: 15개 blocking 레인을 zero-skip으로. create → up --wait → 필수 one-shot →
#       sanitized evidence → 고유 project teardown
./scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json

--lane <id>는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아닙니다.

Optional integration adapters

Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니다. 모듈이 있으면 켜지고, 없으면 그 포트를 구현하는 bean이 아예 없습니다. 아래는 모듈을 고른 뒤 동작을 고르는 키입니다.

  • APP_CACHE_REDIS_ENABLED — deprecated(2026-11-30 제거 예정). 읽는 곳은 sample-portfolio뿐이고, 기본 조립에서 Redis를 켜고 끄는 것은 APP_REDIS_ENABLED입니다.

  • APP_CACHE_CANONICAL_DEFAULT_PROVIDER — canonical default semantic region 선택. disabled(기본) | redis. redis는 canonical Redis CACHE role binding을 함께 요구합니다.

  • APP_CACHE_REDIS_CLIENT_MODE — managed는 내장 Lettuce runtime, external은 프로젝트가 제공한 RedisClient bean을 사용합니다. 아래 세 키는 활성화 스위치가 아니라 선택자입니다. 어떤 capability가 켜지는지는 위의 build 한 줄과 끄는 키가 정하고, 이 값들은 켜진 capability가 무엇으로 동작할지만 고릅니다. 예전에는 "빈 값 = 비활성"으로 설명돼 있었고, 그 문장이 남아 있는 동안 두 개의 활성화 모델이 공존했습니다.

  • APP_MESSAGING_BROKER — 활성 메시지 브로커 id. Kafka 모듈의 설정 기본값이 kafka(등록된 유일한 broker)라 보통 비워 두지 않습니다. 빈 값을 주면 기동이 거부되면서 이 키 이름을 지목합니다. 이 키를 비워도 메시징이 꺼지지는 않습니다 — 끄는 것은 APP_MESSAGING_ENABLED=false입니다.

  • APP_MESSAGING_KAFKA_BROKERS — host:port CSV. Kafka 모듈을 고르면 필수. messaging platform의 Kafka transport(app.messaging.brokers.kafka.bootstrap-servers)가 이 값을 씁니다. spring.kafka.bootstrap-servers는 읽지 않습니다.

  • APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED — Slack webhook R0 provider enable flag. notification 플랫폼이 켜졌을 때 어떤 provider를 쓸지 고르는 값입니다.

  • APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED — Google Email R0 provider enable flag. 위와 같습니다.

Outbound HTTP client

현재 canonical activation은 다음 두 설정 트리만 사용합니다.

app:
  capabilities:
    http-client:
      expected-state: DISABLED
      bindings: {}
  providers:
    http-client: {}
  • 기본 DISABLED는 binding/provider definition이 모두 비어 있어야 하며 DISABLED_VERIFIED만 게시하고 client, executor, pool, retry/CB registry를 만들지 않습니다.
  • ACTIVE는 exact destination/provider/operation-catalog binding을 요구합니다. 현재 유일한 buffered-classic readiness card가 NOT_IMPLEMENTED이므로 provider resource 생성 전에 fail-closed합니다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아닙니다.
  • 기존 APP_OUTBOUND_HTTP_*와 app.outbound.http.*는 canonical 설정이 아닙니다. 루트 src/.env, app-bootstrap의 application YAML, env-key registry에서 제거됐으며 canonical composition에 입력하면 상태와 무관하게 기동을 거부합니다.
  • 다만 sample-portfolio의 application YAML에는 legacy facade를 시연하기 위해 15개 키가 남아 있습니다. 이 모듈은 fixture/reference consumer이고 production 의존성이 아니며, 그 YAML은 :app-bootstrap:verifyEnvKeys가 검사하는 세 파일에 포함되지 않습니다. "제거됐다"는 문장이 저장소 전체를 가리킨다고 읽히지 않도록 범위를 명시합니다.
  • legacy JDK facade가 필요한 fork만 canonical composition 밖에서 OutboundHttpSettings.bindLegacy(Binder)와 legacy configuration을 명시적으로 import합니다. timeout/retry/CB/response-size 설정은 그 migration API 내부 계약일 뿐 canonical provider readiness를 증명하지 않습니다.

Logging

Root / app 레벨 — 허용값은 모두 TRACE | DEBUG | INFO | WARN | ERROR | OFF.

  • APP_LOG_LEVEL_ROOT — root 로거 레벨.
  • APP_LOG_LEVEL_APP — 앱 패키지 레벨.

패키지별 레벨(root 를 덮어씀) — 동일 허용값.

  • APP_LOG_LEVEL_SPRING / APP_LOG_LEVEL_WEB — 각 패키지 레벨.
  • APP_LOG_LEVEL_SQL — DEBUG 로 두면 JPA/jdbc 연결 후 SQL 문이 출력됩니다.

파일 출력 + rolling

  • APP_LOG_FILE_ENABLED — true 면 rolling JSON 파일 appender 를 붙입니다.
  • APP_LOG_FILE_PATH — bootRun working dir(src/) 기준 상대 경로 또는 절대 경로.
  • APP_LOG_FILE_MAX_SIZE — 파일 1개 최대 크기(단위 KB | MB | GB).
  • APP_LOG_FILE_MAX_HISTORY — 보관할 rolled archive 개수. 1 이상 정수.
  • APP_LOG_FILE_TOTAL_SIZE_CAP — 전체 rolled 파일 용량 상한(단위 KB | MB | GB, 0 = 비활성).

Async appender

  • APP_LOG_ASYNC_ENABLED — true 면 appender 를 AsyncAppender 로 감싸 non-blocking I/O.
  • APP_LOG_ASYNC_QUEUE_SIZE — back-pressure 전 in-memory 큐 깊이. 1 이상 정수.
  • APP_LOG_ASYNC_DISCARDING_THRESHOLD — 남은 큐 용량이 이 값 미만이면 TRACE/DEBUG/INFO 이벤트를 버립니다(WARN/ERROR 는 항상 유지). 0 = 절대 버리지 않음. 0 이상 정수.

JSON 인코더 세부

  • APP_LOG_JSON_TIMEZONE — IANA timezone(예: UTC, Asia/Seoul) 또는 default(JVM 기본).
  • APP_LOG_JSON_TIMESTAMP_PATTERN — 타임스탬프 패턴. 보통 ISO 8601 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX).
  • APP_LOG_JSON_INCLUDE_CALLER_DATA — true 면 file/method/line 을 추가. 성능 비용이 큽니다.
  • APP_LOG_JSON_LOGGER_NAME_LENGTH — 0 = 로거 이름 전체, 양수 = 패키지 축약(예: 36 → dev.caskeleton.bootstrap.Foo 가 d.c.bootstrap.Foo 로).

Sampling (SamplingTurboFilter)

  • APP_LOG_SAMPLING_RATE — INFO 이하 로그를 남길 확률. [0.0, 1.0] float. prod 는 0.1(10% 샘플링)이 권장, WARN/ERROR 는 항상 유지. 1.0 = 샘플링 없음(dev/local/staging 기본).

Distributed tracing

  • OTEL_EXPORTER_OTLP_ENDPOINT — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 TracingProperties 가 검증합니다.
  • APP_TRACING_ENABLED — false 면 tracing seam 은 꺼지지만, meta.traceId 는 WebMvcRequestIdFilter 가 W3C traceparent 로 여전히 생성합니다(D4 disabled-fallback 보장).
  • APP_TRACING_SAMPLE_RATE — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float.
    • per-profile 기본값(D6): prod = 0.01, staging = 0.10, dev/local = 1.0.
    • 결정 — 빈 값으로 두는 이유(D-1 ISSUE-1 fix). 빈 값이어야 per-profile resolver 의 기본값이 실제 tracer sampler 까지 도달합니다(TracingSampleRateResolver 가 SSOT). 값을 박으면 프로필별 기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채웁니다.

Privacy: user_principal pseudonymization

  • APP_PRIVACY_PSEUDONYMIZATION_SALT — secret 등급 HMAC-SHA-256 salt. __LOCAL_DEV_ prefix 는 로컬 전용 sentinel 값이며, prod 에서는 secret-manager 가 주입하는 실제 값을 써야 합니다.

Spring Boot bootstrap

  • SPRING_BANNER_MODE — off | console | log.
  • SPRING_MAIN_LAZY_INITIALIZATION — true 면 빈 생성을 첫 사용 시점까지 지연.
  • SPRING_MAIN_LOG_STARTUP_INFO — true 면 Starting/Started 로그 출력.
  • SPRING_THREADS_VIRTUAL_ENABLED — true 면 Tomcat 요청 처리에 Java 21 virtual threads 사용.

Jackson — deserialization policy

모든 request DTO 는 Jackson 경계를 지납니다. 아래 4개 스위치는 잘못된 입력을 조용히 강제 변환하지 않고 즉시 실패하게 만듭니다. 개별 DTO 에 클래스 레벨 @JsonIgnoreProperties(ignoreUnknown = true) 로 이 정책을 완화하는 것은 금지이며 ArchUnit 규칙으로 막혀 있습니다.

  • ..._FAIL_ON_UNKNOWN_PROPERTIES — true: 타입에 선언되지 않은 JSON 키를 거부(Jackson 2.13+ 기본).
  • ..._FAIL_ON_NULL_FOR_PRIMITIVES — true: primitive 필드에 JSON null 이 와도 0/false 로 강제 변환하지 않고 "필수 필드 누락" 에러로 노출. 또는 wrapper 타입(Integer/Long/Boolean) 과 Optional<T> 를 쓰세요.
  • ..._FAIL_ON_IGNORED_PROPERTIES — true: JSON 에 @JsonIgnore 처리된 필드가 들어오면 throw (조용히 버리는 대신 계약 drift 를 노출).
  • ..._READ_UNKNOWN_ENUM_VALUES_AS_NULL — false(Jackson 기본 유지): 모르는 enum 값이 조용히 null 이 되지 않고 throw 되어 VALIDATION_FAILED 로 드러나게 합니다.

Jackson — serialization policy

응답 생성 쪽 정책입니다. 현재 Jackson/Spring Boot 기본값과 같지만 명시적으로 못박아, 미래에 Spring Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니다(spring.mvc.problemdetails.enabled=false 와 같은 근거). JacksonSerializationPolicyTest 가 강제하며, new BigDecimal(double) 생성자는 no_bigdecimal_double_constructor ArchUnit 규칙으로 금지됩니다.

  • ..._WRITE_DATES_AS_TIMESTAMPS — false(D2 / RFC 3339): java.time 값을 ISO-8601 문자열로 직렬화(OffsetDateTime → "...Z", LocalDate → "YYYY-MM-DD"). true 면 epoch 숫자나 [y,m,d,...] 배열로 나가 datetime 계약이 깨집니다.
  • BigDecimal plain output — Jackson 3에는 별도 WRITE_BIGDECIMAL_AS_PLAIN 설정 키가 없습니다. JacksonSerializationPolicyTest 가 "12300000000.00" plain 출력을 직접 검증하고, no_bigdecimal_double_constructor ArchUnit 규칙이 부정확한 new BigDecimal(double) 생성을 금지합니다. 엔드포인트별 string vs number 선택은 그대로 명시적으로 둡니다(공개/금융 API 는 string, 내부 API 는 number+plain).

Server / Tomcat

  • APP_SERVER_PORT — 1~65535 정수.
  • APP_SERVER_SHUTDOWN — graceful | immediate.
  • APP_SERVER_SHUTDOWN_TIMEOUT — duration(예: 30s | 1m | 500ms).
  • APP_SERVER_TOMCAT_MAX_THREADS — 동시 요청 워커 상한. 1 이상 정수.
  • APP_SERVER_TOMCAT_MIN_SPARE_THREADS — idle 워커 풀 하한. 0 이상 정수.
  • APP_SERVER_TOMCAT_ACCEPT_COUNT — 들어오는 TCP 연결의 OS backlog 큐 깊이. 0 이상 정수.
  • APP_SERVER_TOMCAT_MAX_CONNECTIONS — 동시에 열 수 있는 연결 수 상한. 1 이상 정수.
  • APP_SERVER_TOMCAT_CONNECTION_TIMEOUT — duration(예: 20s | 1m).
  • APP_SERVER_COMPRESSION_ENABLED — true | false.
  • APP_SERVER_COMPRESSION_MIN_RESPONSE_SIZE — 이 크기 미만 payload 는 압축하지 않음(bytes 또는 단위, 예: 1024 | 1KB | 2KB).
  • APP_SERVER_FORWARD_HEADERS_STRATEGY — none | native. 기본값은 none. LB/proxy 뒤 배포는 native 로 켜고 server.tomcat.remoteip.internal-proxies 로 신뢰할 프록시를 지정한다. framework 는 모든 peer 의 헤더를 믿으므로 쓰지 않는다.
  • APP_SERVER_ERROR_INCLUDE_STACKTRACE — always | never | on_param.
  • APP_SERVER_ERROR_INCLUDE_MESSAGE — always | never | on_param.

Presentation

  • PRESENTATION_API_BASE_PATH — 모든 controller 앞에 붙는 leading-slash 경로(예: /api | /v1 | "").

Auth (OIDC resource server)

  • APP_SECURITY_JWT_ISSUER — OIDC issuer URI(Keycloak realm, Auth0 tenant 등). 필수 — 없으면 기동 실패. 예: https://keycloak.example.com/realms/ca-skeleton.
  • APP_SECURITY_JWT_AUDIENCE — 기대하는 aud claim(쉼표 목록 가능, 하나라도 맞으면 통과). JWT 모드에서 필수 — 비어 있으면 기동 실패. 이 목록의 client 에 대한 resource_access role 만 권한으로 읽습니다. 예: ca-skeleton-api.
  • SECURITY_PUBLIC_PATHS — 인증을 우회하는 경로 CSV. api-base-path 뒤의 full path 를 씁니다(예: /api/healthcheck). 이 값의 변경은 verifyPublicPathSnapshot 게이트가 감시합니다(위 build.gradle 설명 참조).

CORS

  • APP_SECURITY_CORS_ENABLED — true | false.
  • APP_SECURITY_CORS_ORIGINS — 허용 origin CSV(예: http://localhost:3000,https://app.example.com).
  • APP_SECURITY_CORS_ALLOWED_METHODS — 허용 메서드 CSV. 빈 값이면 기본값 사용(GET, POST, PATCH, PUT, DELETE, OPTIONS).
  • APP_SECURITY_CORS_ALLOWED_HEADERS — 허용 헤더 CSV. * = 모든 헤더 허용.
  • APP_SECURITY_CORS_ALLOW_CREDENTIALS — true | false.
  • APP_SECURITY_CORS_MAX_AGE — preflight 캐시 TTL(초).

프로파일과 데이터베이스

프로파일마다 데이터스토어가 다르고, 그 차이는 app-bootstrap/src/main/resources/application-*.yml 가 소유합니다.

프로파일 데이터스토어 스키마 소유자 외부 인프라
local (기본) PostgreSQL Flyway db/migration/postgresql 필요
dev PostgreSQL Flyway db/migration/postgresql 필요
prod PostgreSQL Flyway db/migration/postgresql 필요
bootRunH2 (명시적 opt-out) H2 in-memory Hibernate ddl-auto: create-drop 없음

./gradlew :app-bootstrap:bootRun 은 기본 local 프로파일에서도 PostgreSQL/Flyway를 사용합니다. 로컬과 운영의 schema owner를 다르게 두면 migration-only 결함을 개발 중에 놓치기 때문에 바뀐 계약입니다. 먼저 아래 Compose PostgreSQL을 띄운 뒤 bootRun을 실행하세요.

Docker 없이 빠르게 wiring·요청/응답·애플리케이션 로직만 확인하려면 ./gradlew :app-bootstrap:bootRunH2를 명시적으로 사용합니다. 이 태스크만 APP_PERSISTENCE_VENDOR=h2, APP_FLYWAY_ENABLED=false, APP_DATASOURCE_DDL_AUTO=create-drop을 주입합니다. H2에는 PostgreSQL migration tree가 없으므로 migration/vendor 계약의 증거로 사용하지 않습니다. 멱등성 provider(APP_IDEMPOTENCY_PROVIDER)는 disabled(기본)나 redis로 둡니다. postgresql은 H2 data source에서 기동을 거부합니다.

dev 를 호스트에서 띄우려면(SPRING_PROFILES_ACTIVE=dev) PostgreSQL 이 필요합니다. docker-compose.local.yml 의 db 서비스가 루프백(127.0.0.1:5433)에만 게시하며, 이 주소가 아래 APP_DATASOURCE_URL 의 커밋된 기본값입니다. 저장소 루트에서 실행합니다.

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --wait db

컨테이너로 띄우는 scripts/bootstrap-local.sh 경로는 이 호스트 포트를 쓰지 않습니다. compose 가 app 컨테이너의 APP_DATASOURCE_URL 을 내부 네트워크 주소 jdbc:postgresql://db:5432/... 로 덮어씁니다.

app.persistence.vendor(postgresql | h2)가 어느 vendor 구성을 조립할지 고르는 단일 스위치입니다. 값이 둘 중 하나가 아니면 기동이 실패하고, prod 에서 h2 이거나 datasource URL 이 jdbc:h2: 이면 PersistenceVendorProdSafetyValidator 가 기동을 거부합니다(env 로 덮어써도 동일).

Database (Postgres)

  • APP_DATASOURCE_URL — JDBC URL(예: jdbc:postgresql://host:5432/dbname). dev·prod 에서 쓰이며, 커밋된 기본값 jdbc:postgresql://localhost:5433/ca_skeleton 은 위 compose db 서비스의 호스트 주소입니다.
  • APP_DATASOURCE_USERNAME / APP_DATASOURCE_PASSWORD — DB 접속 계정.
  • APP_DATASOURCE_DRIVER — Hibernate dialect 에 맞는 드라이버(예: org.postgresql.Driver).
  • APP_DATASOURCE_DDL_AUTO — none | validate | update | create | create-drop. prod 는 validate 또는 none(JpaDangerousConfigurationGuard 가 기동 시 강제). local 은 이 값을 쓰지 않습니다 — application-local.yml 이 create-drop 으로 고정합니다.
  • APP_DATASOURCE_SHOW_SQL — true 면 SQL 을 로그로 echo.
  • APP_DATASOURCE_FORMAT_SQL — SQL pretty-print(SHOW_SQL=true 일 때만 의미 있음).
  • APP_DATASOURCE_OPEN_IN_VIEW — Hibernate OSIV. prod 에서는 피하세요.

HikariCP 커넥션 풀

  • APP_DATASOURCE_POOL_MAX_SIZE — DB 동시 연결 최대 수. 1 이상 정수.
  • APP_DATASOURCE_POOL_MIN_IDLE — warm 하게 유지하는 최소 idle 연결 수. 0 이상 정수.
  • APP_DATASOURCE_CONNECTION_TIMEOUT — acquire() 가 실패하기 전 대기 시간(ms).
  • APP_DATASOURCE_POOL_IDLE_TIMEOUT — idle 연결 회수 임계 시간(ms).
  • APP_DATASOURCE_POOL_MAX_LIFETIME — 연결의 최대 수명(ms). broker timeout 전에 rotate 하도록 설정합니다.

Management / Actuator

  • 결정 — management 포트 분리. actuator 엔드포인트를 앱 API 와 같은 소켓에 노출하지 않으려고 별도 management 포트를 둡니다.
  • MANAGEMENT_SERVER_PORT — 1~65535 정수. APP_SERVER_PORT(8080)와 달라야 합니다.