Files
clean-architecture-backend-…/src
DongHyeonka d46bab9659
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).

소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.

- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
  `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
  (trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
  configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
  PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
  jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
  레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
  앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
  `needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
  저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
  계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
  바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
  선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
  run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
  needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
  working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
  하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
  (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
  TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
  트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
  손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
  포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
  RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
  .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
  AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
  docs/upgrade B-57~B-61.

버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.

위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.

BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
2026-11-08 21:55:43 +09:00
..

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

src/ 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 AGENTS.md, 모듈별 규칙은 각 모듈의 AGENTS.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을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: -Predis.topology.mode, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력
performanceCheck 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(-Pperformance.assertions.enabled가 true가 아니면 실패, skip된 테스트가 있어도 실패). main.yml performance job이 nightly에 다른 무거운 job 뒤에서 같은 명령으로 돌림
verifyStrictLaneStages --dry-run 전용. explicitOnly가 아닌 strict lane이 strictLaneStages에 선언한 단계(prCheck·mainCheck·integrationCheck·performanceCheck·releaseCheck) 중 하나의 계획에 있는지, 단계마다 선언한 workflow job이 ./gradlew <단계>를 정해진 한 줄로 조건 없이(또는 선언한 조건으로) 돌리는지 검사. 형식은 build-logic/AGENTS.md 「단계 job의 모양」. PR 단계가 돌림
prCheck PR 단계: ci + verifyDependencyLocks + compose 렌더링(verifyComposeProfiles) + 저장소 배치(verifyRepositoryLayout) + 문서 검사(documentCheck)
ci 모든 leaf check(API surface 검사 포함, 소유자 결정 20) + architectureCheck + qualityCheck
mainCheck main 단계: configContractCheck + qualificationCheck + 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/design/2026-09-16-verification-surface-reduction-design.md.

로컬 첫 실행

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

추적 가능한 버전과 의존성 잠금

  • 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를 조용히 다시 쓰지 못하게 한다.

재현 가능한 아카이브 (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와 .gitea/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와 workflow job graph 그 자체다.

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

  • 워크플로. .gitea/workflows/의 세 파일이다. pr.yml의 done job이 PR 단계의 모든 job(gradle: ./gradlew :prCheck와 verifyStrictLaneStages --dry-run, vulnerabilities: Trivy)을 모으는 단일 필수 검사다. main.yml이 main 단계(mainCheck·integrationCheck·build-logic 시험·configuration cache·링크)와 nightly(행렬 job, compose smoke, 마지막에 performanceCheck)를, release.yml이 태그 단계를 돌린다. 무엇을 돌릴지는 Gradle 단계 태스크가 정하고, verifyStrictLaneStages가 단계 job의 모양을 지킨다.


.env — 환경 변수 레퍼런스

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

앱 이름과 profile

  • APP_NAME — spring.application.name 과 JSON 로그의 app 필드. 자유 문자열.
  • SPRING_PROFILES_ACTIVE — 활성 Spring profile. local | dev | prod 중 정확히 하나다. JSON 로그의 profile 필드도 이 값을 쓴다.

런타임 안전 검사 (기동할 때 바로 실패시킨다, 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 — 제공자에 묶이지 않은 앞단 요청 수 제한(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도 함께 올린다.

비동기 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 최소 버전은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json의 minimumComposeVersion이다. 정본 스크립트가 검증한다. lane은 저장소 루트 compose.yaml(개발 환경)을 바탕으로 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/app-bootstrap/compose-lanes/에 있다.
  • 진입점은 둘뿐이고, 그 둘만이 증거다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이 초록으로 보고된다.
# 정적: profile별 정확한 service set, 병합된 모델 전체, mount target 유일성
./scripts/verify-compose-profile-contracts.sh

# 동적: 계약의 blocking 레인을 zero-skip으로. create → up --wait → 필수 one-shot →
#       컨테이너 재시작·OOM 0 확인 → sanitized evidence → 고유 project teardown
./scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json

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

선택형 연동 adapter

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

  • APP_CACHE_REDIS_ENABLED — deprecated(2026-11-30 제거 예정). 읽는 곳이 없고, 기본 조립에서 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 제공자를 켜는 값. notification 플랫폼이 켜졌을 때 어떤 provider를 쓸지 고르는 값이다.

  • APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED — Google Email R0 제공자를 켜는 값. 위와 같다.

외부 HTTP 호출 (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에 입력하면 상태와 무관하게 기동을 거부한다.
  • 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠다. 이제 저장소 어디에도 남아 있지 않다.
  • legacy JDK facade가 필요한 fork만 canonical composition 밖에서 OutboundHttpSettings.bindLegacy(Binder)와 legacy configuration을 명시적으로 import한다. timeout/retry/CB/response-size 설정은 그 migration API 내부 계약일 뿐 canonical provider readiness를 증명하지 않는다.

로그

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 기본).

분산 추적

  • 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.
    • profile별 기본값(D6): prod = 0.01, dev/local = 1.0.
    • 결정 — 빈 값으로 두는 이유(D-1 ISSUE-1 fix). 빈 값이어야 per-profile resolver 의 기본값이 실제 tracer sampler 까지 도달한다(TracingSampleRateResolver 가 SSOT). 값을 박으면 프로필별 기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채운다.

개인정보: user_principal 가명화

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

Spring Boot 기동

  • 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 — 역직렬화 정책

모든 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 — 직렬화 정책

응답 생성 쪽 정책이다. 현재 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).

서버 / 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 | "").

인증 (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 이 필요하다. compose.yaml 의 db 서비스(jpa profile)가 루프백(127.0.0.1:5433)에만 게시하며, 이 주소가 아래 APP_DATASOURCE_URL 의 커밋된 기본값이다. 저장소 루트에서 실행한다.

docker compose 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 로 덮어써도 동일).

데이터베이스 (PostgreSQL)

  • 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 하도록 설정한다.

관리 포트 / Actuator

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