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.
This commit is contained in:
DongHyeonka
2026-11-07 12:52:36 +09:00
parent a025f244c7
commit 50cd7154d0
85 changed files with 1073 additions and 1022 deletions
+2 -2
View File
@@ -26,7 +26,7 @@ jobs:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Start the NFSv4 certification environment
run: docker compose -f infra/fileserver/nfs/compose.yml up -d --wait
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait
- name: Run the network-filesystem ambiguity suite
working-directory: src
run: >-
@@ -35,7 +35,7 @@ jobs:
--stacktrace
- name: Tear down the NFS environment
if: always()
run: docker compose -f infra/fileserver/nfs/compose.yml down -v
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v
fileserver-process-kill-matrix:
runs-on: ubuntu-latest
+2 -2
View File
@@ -24,8 +24,8 @@ on:
- 'src/.env'
- 'docs/registries/env-keys.yaml'
- 'src/Dockerfile'
- 'docker-compose.yml'
- 'infra/fileserver/nfs/**'
- 'compose.yaml'
- 'src/app-bootstrap/compose-lanes/fileserver.yaml'
- '.github/workflows/fileserver-pr.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
+1 -1
View File
@@ -272,7 +272,7 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Run every blocking Compose runtime lane
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
- name: Publish sanitized runtime-smoke evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
+1 -1
View File
@@ -30,7 +30,7 @@ on:
- 'src/config/architecture/modules.json'
- 'src/.env'
- 'docs/notification/**'
- 'infra/notification/**'
- 'src/app-bootstrap/compose-lanes/smoke/notification-smoke.sh'
- '.github/workflows/notification-platform.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
+5 -5
View File
@@ -1,6 +1,6 @@
# Redis SDK topology evidence.
#
# The lanes in infra/redis-sdk answer what the deterministic in-memory gateway cannot — Sentinel
# The lanes in src/adapter/outbound/redis-sdk/compose answer what the deterministic in-memory gateway cannot — Sentinel
# promotion behaviour, Cluster redirects, ACL coverage. docs/redis/support-matrix.md records which
# lane produced which evidence, and RedisSupportMatrixTest refuses an evidence claim that does not
# name the test class behind it.
@@ -34,7 +34,7 @@ on:
- "src/adapter/outbound/redis-runtime/**"
- "src/adapter/outbound/redis-sdk/**"
- "src/adapter/outbound/cache-redis/**"
- "infra/redis-sdk/**"
- "compose/redis/**"
- ".github/workflows/redis-sdk-topology.yml"
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
@@ -122,7 +122,7 @@ jobs:
- name: Start the topology
env:
REDIS_VERSION: ${{ matrix.redis_version }}
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" up -d --wait
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" up -d --wait
- name: Record the image digest
id: image
run: |
@@ -161,7 +161,7 @@ jobs:
# however loudly the file is named "test".
tls)
port=6390
docker compose -f ../infra/redis-sdk/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
docker compose -f adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem"
tasks="$runtime"
;;
@@ -199,4 +199,4 @@ jobs:
retention-days: 90
- name: Stop the topology
if: always()
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" down -v
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" down -v
+7 -3
View File
@@ -36,10 +36,10 @@ test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain`
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
```bash
scripts/bootstrap-local.sh # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>
scripts/bootstrap-local.sh
```
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
```bash
curl -fsS http://localhost:8080/api/healthcheck
@@ -48,9 +48,13 @@ curl -fsS http://localhost:8080/api/healthcheck
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
```bash
docker compose -f docker-compose.yml -f docker-compose.local.yml down
docker compose --profile '*' down
```
`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다.
Redis·Kafka·MongoDB 같은 뒷단 서비스는 `compose.yaml`의 profile로 고릅니다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있습니다.
`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다.
### 기본 조립과 부가 기능
+426
View File
@@ -0,0 +1,426 @@
# =============================================================================
# 개발 환경 — 이 repo의 compose 파일은 이것 하나다.
#
# docker compose up -d --wait app # 앱 컨테이너(기본 조립, local 런타임)
# docker compose up -d --wait db # 뒷단 서비스 하나만(이름을 대면 그 profile이 켜진다)
# docker compose --profile jpa --profile redis up -d --wait # 뒷단 서비스 묶음
# docker compose --profile '*' down # 내린다. 데이터까지 지우려면 down -v
#
# 내릴 때 --profile '*'를 붙인다. 붙이지 않으면 compose는 켜진 profile의 서비스만 내리므로, 이름으로
# 띄운 db 같은 profile 서비스가 남는다.
#
# 뒷단 서비스는 capability 이름의 profile로 고른다. profile을 대지 않으면 app만 뜬다.
#
# profile 서비스 쓰는 기능
# jpa db (PostgreSQL 16) JPA
# redis redis (ACL 계정) Redis
# kafka kafka Kafka 발행
# mongo mongo, mongo-rs-init MongoDB
# objectstorage minio, minio-init 객체 저장소
# auth keycloak JWT 발급자
# mail mailpit (STARTTLS 필수) SMTP 발송
#
# 이 파일이 마운트하는 보조 파일은 compose/ 아래에 있다. compose lane(테스트)은 이 파일을 바탕으로
# 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/app-bootstrap/compose-lanes/에 있다.
# 경로는 모두 이 파일이 있는 저장소 루트 기준이다.
#
# auth profile은 keycloak client secret 파일이 있어야 뜬다. lane은 실행마다 만들고 지운다. 손으로 띄울
# 때는 compose/keycloak/secrets/graphql-smoke-client-secret에 아무 값이나 한 줄 넣는다(그 폴더는
# Git이 무시한다). mail profile도 같다: compose/mailpit/tls/에 server.crt·server.key가 있어야 한다.
#
# 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)
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
#
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
# DeveloperExperienceContractTest fails when this value is below the sum.
#
# 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. A compose lane that boots every
# capability at once raises it for itself (compose-profile-contracts.json, appMemoryLimit).
# =============================================================================
# The local MinIO runtime, used by the server below and by the lane's object storage smoke client.
#
# It is the image the MinIO qualification lanes measured, by the same digest:
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
# leaf fails when this default (or the lane file's copy) and the evidence disagree. Change them
# together.
#
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
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}
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
# was marked optional, untracking that file made `docker compose config` fail outright on a
# clone. The tracked contract is src/.env.example; copy it. A compose lane does not depend on it:
# its values go into a generated `environment:` block, which outranks every env_file.
env_file:
- path: ./src/.env
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
# Management (health, info, prometheus — answered without authentication) on loopback only:
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
# inside the container, so they need no host port at all.
- "127.0.0.1:9001:9001"
environment:
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
# environment the application believes it is in. The dev and prod-smoke lane overlays set
# their own.
SPRING_PROFILES_ACTIVE: "local"
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"
# The `db` service below, on the internal network. The default composition does not read
# these; a service that selects the relational capability does.
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
# ---- 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
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
# mount in its own overlay, added with -f when the capability is selected, so this file never
# names one (07-08).
# ---- 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) + async wait (19s) + preStop (5s)
# + margin (6s) = 60s.
stop_grace_period: 60s
# ---- Health check -------------------------------------------------------
# The actuator readiness probe on the management port (9001). It answers under every runtime
# (local, dev, prod), unlike the public health path, whose base path differs by runtime.
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:9001/actuator/health/readiness"
interval: 5s
timeout: 3s
start_period: 60s
retries: 12
restart: unless-stopped
networks:
- caskeleton-infra
# ---- PostgreSQL --------------------------------------------------------------
# Published on the loopback interface only, so a host-side run (`./gradlew :app-bootstrap:bootRun`,
# IDE) reaches the same database the containerised app reaches over the internal network. The
# port is the one src/.env.example's APP_DATASOURCE_URL names.
db:
profiles:
- jpa
image: postgres:16-alpine
environment:
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
TZ: "UTC"
volumes:
- type: volume
source: caskeleton-db-data
target: /var/lib/postgresql/data
ports:
- "127.0.0.1:5433:5432"
networks:
- caskeleton-infra
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
# ---- MongoDB -----------------------------------------------------------------
# A replica set of one. Single-node is still a replica set: transactions and change streams need
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
# difference at the first transaction.
mongo:
profiles:
- mongo
image: mongo:8.0.16
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
volumes:
- type: volume
source: caskeleton-mongo-data
target: /data/db
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
mongo-rs-init:
profiles:
- mongo
image: mongo:8.0.16
depends_on:
mongo:
condition: service_healthy
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
# stack can be re-run against a surviving volume without a manual reset.
command:
- mongosh
- --host
- mongo
- --quiet
- --eval
- >-
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
networks:
- caskeleton-infra
restart: "no"
# ---- Kafka -------------------------------------------------------------------
kafka:
profiles:
- kafka
image: apache/kafka:3.8.0
environment:
KAFKA_NODE_ID: "1"
KAFKA_PROCESS_ROLES: "broker,controller"
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
networks:
- caskeleton-infra
healthcheck:
test:
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
# ---- Redis -------------------------------------------------------------------
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
# compose/redis/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
# a lane-only `+@all` account (compose/redis/acl/README.md). Its first line turns the passwordless
# `default` user off, so the application connects as the named accounts the lane contract gives it
# (compose-profile-contracts.json, $redisComment).
#
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
# The application then logged that trade, and the missing advanced account, as two startup
# warnings — correctly, because in production both are risks — and every Redis lane failed its
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
# lane now authenticates the way a deployment does instead.
#
# The passwords are the file's fixture values (compose/redis/acl/README.md); this container is
# on the internal network only and publishes no port.
redis:
profiles:
- redis
image: redis:7.4
command:
- redis-server
- --appendonly
- "no"
- --save
- ""
- --aclfile
- /etc/redis/acl/lane-fixture-accounts.acl
volumes:
- type: bind
source: ./compose/redis/acl
target: /etc/redis/acl
read_only: true
networks:
- caskeleton-infra
healthcheck:
test:
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
- "CMD-SHELL"
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- Mailpit — the reference SMTP relay ----------------------------------------
mailpit:
profiles:
- mail
image: axllent/mailpit:v1.21
environment:
MP_SMTP_AUTH_ACCEPT_ANY: "1"
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
# any AUTH now happens inside the TLS session.
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A stack
# that wanted a plaintext Mailpit would be asking for a transport the type refuses to express,
# and the honest way to satisfy it is to give the relay a certificate.
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
MP_SMTP_REQUIRE_STARTTLS: "true"
volumes:
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
# private key in Git.
- type: bind
source: ./compose/mailpit/tls
target: /run/mailpit-tls
read_only: true
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "/mailpit", "readyz"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- MinIO -------------------------------------------------------------------
minio:
profiles:
- objectstorage
image: *local-minio-image
command: ["server", "/data"]
environment:
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
volumes:
- type: volume
source: caskeleton-minio-data
target: /data
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 10s
timeout: 5s
retries: 10
start_period: 10s
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
# server accepts an admin command, not that an object survives being written and read back.
minio-init:
profiles:
- objectstorage
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
# it has no shell, and the bootstrap below is a shell script.
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
depends_on:
minio:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./compose/minio/init
target: /opt/minio
read_only: true
networks:
- caskeleton-infra
restart: "no"
# ---- Keycloak ----------------------------------------------------------------
keycloak:
profiles:
- auth
image: quay.io/keycloak/keycloak:26.0
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
# command line.
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
KC_HEALTH_ENABLED: "true"
volumes:
- type: bind
source: ./compose/keycloak/entrypoint.sh
target: /opt/keycloak-entrypoint/entrypoint.sh
read_only: true
- type: bind
source: ./compose/keycloak/realms
target: /opt/keycloak/data/import
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
healthcheck:
test:
- "CMD-SHELL"
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
interval: 10s
timeout: 5s
retries: 20
start_period: 30s
networks:
caskeleton-infra:
driver: bridge
volumes:
caskeleton-db-data:
driver: local
caskeleton-mongo-data:
driver: local
caskeleton-minio-data:
driver: local
secrets:
keycloak-graphql-smoke-client-secret:
file: ./compose/keycloak/secrets/graphql-smoke-client-secret
@@ -1,6 +1,6 @@
# Keycloak realm artifact
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in `docker-compose.infra.yml`
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml`
and is the same realm every GraphQL qualification lane authenticates against.
## The client secret is a reference, never a value
@@ -42,9 +42,10 @@ a fork that copied one of them got an open account and a green lane.
## Who loads `lane-fixture-accounts.acl`
The Redis topology lanes (`../standalone`, `../sentinel`, `../cluster`, `../tls`) and the
The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the
application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in
`src/config/runtime/compose-profile-contracts.json`). Both mount this directory read-only; neither
`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's
`redis` service (root `compose.yaml`). They all mount this directory read-only; neither
keeps a copy, because a second copy of these lines is a second place for a password or a key
pattern to drift.
-579
View File
@@ -1,579 +0,0 @@
# =============================================================================
# Shared infrastructure, owned here and nowhere else.
#
# Environment overlays (local, dev, prod-smoke) describe how the application runs. This file
# describes what it runs against. Keeping the two apart is why `local` could stop meaning "the app
# plus a database" and start meaning "the app, with whichever services the lane asked for".
#
# Every service carries a Compose profile, so nothing here starts unless a lane names it. A profile
# selects services; it never implies a Spring profile. The lane definitions live in
# src/config/runtime/compose-profile-contracts.json, and scripts/verify-compose-profile-contracts.sh
# checks this file against them.
# =============================================================================
# The local MinIO runtime, used by the server and by the object-storage smoke client below.
#
# It is the image the MinIO qualification lanes measured, by the same digest:
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
# leaf fails when this default and the evidence disagree. Change both together.
#
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
services:
# ---- PostgreSQL --------------------------------------------------------------
db:
profiles:
- local-jpa
- local-messaging-outbox
- local-fileserver
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- shared-infra
- prod-smoke
- all-adapters
image: postgres:16-alpine
environment:
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
TZ: "UTC"
volumes:
- type: volume
source: caskeleton-db-data
target: /var/lib/postgresql/data
ports:
- "127.0.0.1:5433:5432"
networks:
- caskeleton-infra
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
# ---- MongoDB -----------------------------------------------------------------
# A replica set of one. Single-node is still a replica set: transactions and change streams need
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
# difference at the first transaction.
mongo:
profiles:
- local-mongo
- all-adapters
image: mongo:8.0.16
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
volumes:
- type: volume
source: caskeleton-mongo-data
target: /data/db
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
mongo-rs-init:
profiles:
- local-mongo
- all-adapters
image: mongo:8.0.16
depends_on:
mongo:
condition: service_healthy
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
# lane can be re-run against a surviving volume without a manual reset.
command:
- mongosh
- --host
- mongo
- --quiet
- --eval
- >-
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
networks:
- caskeleton-infra
restart: "no"
# ---- Kafka -------------------------------------------------------------------
kafka:
profiles:
- local-messaging
- local-messaging-outbox
- all-adapters
image: apache/kafka:3.8.0
environment:
KAFKA_NODE_ID: "1"
KAFKA_PROCESS_ROLES: "broker,controller"
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
networks:
- caskeleton-infra
healthcheck:
test:
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
# ---- Redis — local compose contract for the shipped Redis runtime ----------------
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
# infra/redis-sdk/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
# a lane-only `+@all` account (infra/redis-sdk/acl/README.md). Its first line turns the passwordless
# `default` user off, so the application connects as the named accounts the lane contract gives it
# (compose-profile-contracts.json, $redisComment).
#
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
# The application then logged that trade, and the missing advanced account, as two startup
# warnings — correctly, because in production both are risks — and every Redis lane failed its
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
# lane now authenticates the way a deployment does instead.
#
# The passwords are the file's fixture values (infra/redis-sdk/acl/README.md); this container is
# on the lane's internal network only and publishes no port.
redis:
profiles:
- local-redis
- all-adapters
image: redis:7.4
command:
- redis-server
- --appendonly
- "no"
- --save
- ""
- --aclfile
- /etc/redis/acl/lane-fixture-accounts.acl
volumes:
- type: bind
source: ./infra/redis-sdk/acl
target: /etc/redis/acl
read_only: true
networks:
- caskeleton-infra
healthcheck:
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
test:
- "CMD-SHELL"
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- Mailpit — the reference SMTP provider for notification serving ----------
mailpit:
profiles:
- local-notification-serving
- local-notification-handoff
- all-adapters
image: axllent/mailpit:v1.21
environment:
MP_SMTP_AUTH_ACCEPT_ANY: "1"
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
# any AUTH now happens inside the TLS session.
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A lane that
# wanted a plaintext Mailpit would be asking for a transport the type refuses to express, and
# the honest way to satisfy it is to give the relay a certificate.
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
MP_SMTP_REQUIRE_STARTTLS: "true"
volumes:
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
# private key in Git.
- type: bind
source: ./infra/mailpit/tls
target: /run/mailpit-tls
read_only: true
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "/mailpit", "readyz"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- MinIO -------------------------------------------------------------------
minio:
profiles:
- shared-infra
- prod-smoke
image: *local-minio-image
command: ["server", "/data"]
environment:
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
volumes:
- type: volume
source: caskeleton-minio-data
target: /data
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 10s
timeout: 5s
retries: 10
start_period: 10s
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
# server accepts an admin command, not that an object survives being written and read back.
minio-init:
profiles:
- shared-infra
- prod-smoke
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
# it has no shell, and the bootstrap below is a shell script.
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
depends_on:
minio:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./infra/minio/init
target: /opt/minio
read_only: true
networks:
- caskeleton-infra
restart: "no"
# ---- Keycloak ----------------------------------------------------------------
keycloak:
profiles:
- local-graphql
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- shared-infra
- prod-smoke
- all-adapters
image: quay.io/keycloak/keycloak:26.0
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
# command line.
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
KC_HEALTH_ENABLED: "true"
volumes:
- type: bind
source: ./infra/keycloak/entrypoint.sh
target: /opt/keycloak-entrypoint/entrypoint.sh
read_only: true
- type: bind
source: ./infra/keycloak/realms
target: /opt/keycloak/data/import
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
healthcheck:
test:
- "CMD-SHELL"
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
interval: 10s
timeout: 5s
retries: 20
start_period: 30s
# ---- Capability schema streams ------------------------------------------------
# Two pre-start one-shots, in this order, because a capability stream is an operator sequence
# rather than a property.
#
# Install: each stream under db/migration/jpa keeps its own Flyway history table — they all declare
# a V1, so one Flyway pointed at all of them fails outright — and each registers itself
# INSTALLED_INACTIVE.
#
# Promote: an operator sanctions the installed schema, and the application refuses to start until
# that has happened. That is the fail-closed half of the same design, so it cannot be folded into
# the install step without making "the tables exist" and "this is sanctioned" the same event.
#
# They are also two images because they must be: flyway/flyway ships no psql, so the promotion
# could not have run in the migration container at all.
#
# Both run before `up`, not with the smoke clients after it — the application is what they are a
# precondition for. The lane contract's preStartServices carries that ordering.
db-migrate-capabilities:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- local-fileserver
- all-adapters
image: flyway/flyway:11.1.0
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/apply-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./infra/postgres/apply-capability-streams.sh
target: /opt/capability-streams/apply-capability-streams.sh
read_only: true
# The whole migration tree, not just db/migration/jpa: the application's own postgresql stream
# has to be installed first, or the capability tables arrive in a schema whose flyway_schema_history
# does not exist yet and the application refuses to start — which is its baseline-on-migrate: false
# policy working as designed.
- type: bind
source: ./src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
target: /flyway/sql
read_only: true
# Each capability stream from the leaf that owns it, beside rather than inside /flyway/sql: a
# bind mount nested in that read-only one would need its mount point created in the source
# tree. They moved out of persistence-jpa with their capabilities, and the mount above stopped
# reaching them — the script then refused with "no such stream".
- type: bind
source: ./src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform
target: /flyway/streams/notification-platform
read_only: true
- type: bind
source: ./src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver
target: /flyway/streams/fileserver
read_only: true
networks:
- caskeleton-infra
restart: "no"
db-promote-capabilities:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- local-fileserver
- all-adapters
image: postgres:16-alpine
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/promote-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./infra/postgres/promote-capability-streams.sh
target: /opt/capability-streams/promote-capability-streams.sh
read_only: true
networks:
- caskeleton-infra
restart: "no"
# The GraphQL transport, as a request. auth-smoke proves a token can be obtained and that public
# health answers; this proves /graphql is guarded and that an authenticated query executes.
graphql-smoke:
profiles:
- local-graphql
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the mounted 0600 client secret, same as auth-smoke.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/graphql-smoke/graphql-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
# Spring for GraphQL serves its own endpoint through a router function rather than an
# annotated controller, so the presentation base-path prefix does not apply to it.
GRAPHQL_PATH: "${GRAPHQL_PATH:-/graphql}"
volumes:
- type: bind
source: ./infra/graphql/smoke
target: /opt/graphql-smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
# ---- One-shot smoke clients --------------------------------------------------
# Never `up --wait` targets. Each is run with `run --rm` and must exit zero; a missing, skipped or
# non-zero one fails its lane rather than being treated as "not applicable".
auth-smoke:
profiles:
- local-graphql
- shared-infra
- prod-smoke
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# The client secret is written on the host at mode 0600 by the qualification wrapper and mounted
# in. The Keycloak image happens to run as the same uid the wrapper writes as; this image runs as
# uid 100, so it read "Permission denied" and the lane failed on the smoke client rather than on
# anything it was checking. Compose ignores the secret's uid/gid/mode options outside swarm, so
# the container reads it as root instead. The two alternatives are both worse: loosening the host
# file to world-readable leaves a credential readable by every process on the machine, and passing
# the value as an environment variable puts it in `docker compose config` output and in ps.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/auth-smoke/auth-smoke.sh"]
environment:
# The same issuer URL the application is given. A token obtained from one URL and validated
# against another proves nothing, and localhost means a different host inside each container.
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
APP_BASE_URL: "http://app:8080"
# Supplied per runtime, because the same endpoint has two addresses: application-local.yml
# pins presentation.api-base-path to /api and the shipped default is /v1. The qualification
# wrapper exports the value that matches the lane's Spring runtime.
APP_HEALTH_PATH: "${APP_HEALTH_PATH:-/v1/healthcheck}"
volumes:
- type: bind
source: ./infra/keycloak/smoke
target: /opt/auth-smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
# The server image, not the mc client image: the mc image ships no sed, grep or cmp, and the round-trip
# client needs a digest tool. See infra/minio/smoke/object-storage-smoke.sh for how that went
# unnoticed. The lane already pulls this image for the server itself.
object-storage-smoke:
profiles:
- shared-infra
- prod-smoke
image: *local-minio-image
depends_on:
minio-init:
condition: service_completed_successfully
entrypoint: ["/bin/sh", "/opt/minio-smoke/object-storage-smoke.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./infra/minio/smoke
target: /opt/minio-smoke
read_only: true
networks:
- caskeleton-infra
restart: "no"
notification-smoke:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the same reason auth-smoke uses it: the mounted client secret is mode 0600 on the
# host and this image otherwise runs as uid 100, which reads "Permission denied". The lane then
# fails on the smoke client rather than on anything it was checking.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/notification-smoke/notification-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
MAILPIT_BASE_URL: "http://mailpit:8025"
# ingest | serving | handoff-verify — which phase of the lane this invocation is.
#
# No default, deliberately. It defaulted to `ingest`, and local-notification-serving therefore
# ran the ingest assertions — "accepted, and nothing was delivered" — against an application in
# SERVING mode. The lane passed while testing the opposite of what it is named for, and would
# have kept passing for as long as the check happened to run before the dispatch worker. An
# unset value now renders empty and the client refuses it.
# `:-` and not a value: an explicit empty default keeps Compose from warning about an unset
# variable on every lane that never runs this client, while still rendering empty so the
# client refuses it.
NOTIFICATION_SMOKE_PHASE: "${NOTIFICATION_SMOKE_PHASE:-}"
# Submission and template publication are authenticated like every other non-public path, so
# this client obtains a token the same way auth-smoke does — client credentials against the
# same issuer URL the application validates against.
APP_BASE_PATH: "${APP_BASE_PATH:-/api}"
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
volumes:
- type: bind
source: ./infra/notification/smoke
target: /opt/notification-smoke
read_only: true
# The handoff lane runs this client twice in one project and the second run needs the request
# id the first accepted, so the state lives in a named volume that outlives a `run --rm`
# container and is removed with the project by the teardown's --volumes.
#
# Its own path, not a subdirectory of the script mount above: a volume nested inside a
# read-only bind cannot be created, because the runtime has to mkdir the mountpoint in a
# filesystem it was just told is read-only.
- type: volume
source: caskeleton-notification-smoke-state
target: /opt/notification-smoke-state
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
networks:
caskeleton-infra:
driver: bridge
volumes:
caskeleton-notification-smoke-state:
driver: local
caskeleton-db-data:
driver: local
caskeleton-mongo-data:
driver: local
caskeleton-minio-data:
driver: local
secrets:
# Written per run at mode 0600 by the qualification wrapper and removed on teardown. The realm
# artifact references it by name; the value never reaches Git, a rendered config, a command line,
# or an evidence file.
keycloak-graphql-smoke-client-secret:
file: ./infra/keycloak/secrets/graphql-smoke-client-secret
-64
View File
@@ -1,64 +0,0 @@
# =============================================================================
# feature-container-runtime-contract — local infrastructure override
#
# Merge with base (and optionally dev):
# docker compose -f docker-compose.yml -f docker-compose.local.yml up
#
# Local intent:
# - Wires the app environment to point at the shared `db` service, which lives in
# docker-compose.infra.yml and starts only for lanes whose Compose profile names it.
# - Declares no depends_on: a depends_on aimed at a profiled service makes every lane that does
# not enable that profile fail to render at all, and ordering is the runtime-smoke wrapper's
# job — it knows which services a lane actually starts.
# - Keeps read-only filesystem and memory limits from the base compose.
# - Publishes the DB on the loopback interface only, so a host-side run
# (`./gradlew :app-bootstrap:bootRun`, IDE) reaches the same database the
# containerised app reaches over the internal `caskeleton-local` network.
# =============================================================================
services:
app:
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
# was marked optional, untracking that file made `docker compose config` fail outright on a
# clone — the environment override that exists for convenience became a hard prerequisite for
# rendering the stack at all. The tracked contract is src/.env.example; copy it.
env_file:
- path: ./src/.env
required: false
# Wire the app to the local Postgres service on the internal network.
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: "local"
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# fallback matches env-keys.yaml SSOT default (30s); base compose grace is 60s.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# Database connection — points to the local `db` service below.
# Override with your actual DB credentials in a local .env file.
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:8080/api/healthcheck"
interval: 5s
timeout: 3s
start_period: 20s
retries: 12
networks:
- caskeleton-infra
networks:
# Defined in docker-compose.infra.yml, where the services that share it live.
caskeleton-infra:
external: false
-107
View File
@@ -1,107 +0,0 @@
# =============================================================================
# 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)
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
#
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
# DeveloperExperienceContractTest fails when this value is below the sum.
#
# Ownership: env-driven-config owns the app shutdown *value* (30s); this contract owns the
# *relationship* (stop_grace_period >= app timeout + async wait + 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"
# Management (health, info, prometheus — answered without authentication) on loopback only:
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
# inside the container, so they need no host port at all.
- "127.0.0.1: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
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
# mount in its own overlay file under infra/<capability>/compose/, added with -f when the
# capability is selected, so this file never names one (07-08).
# ---- 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) + async wait (19s) + preStop (5s)
# + margin (6s) = 60s.
stop_grace_period: 60s
# ---- 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
+1 -1
View File
@@ -48,7 +48,7 @@ certification that does not name all five is not transferable.
## Network filesystems
```bash
docker compose -f infra/fileserver/nfs/compose.yml up -d
docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d
FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test
```
+1 -1
View File
@@ -68,7 +68,7 @@ nothing in this repository has executed against 7.2 or 8.2.
### What the standalone ACL run established
`RedisTopologyContractTest` runs the four accounts in `infra/redis-sdk/acl` against a live server and
`RedisTopologyContractTest` runs the four accounts in `compose/redis/acl` against a live server and
asserts that each `CommandAccess` level grants exactly what the command policy catalog says it may
issue. Writing it found five defects that no amount of reading the files would have surfaced:
+1 -1
View File
@@ -42,7 +42,7 @@ actually run.
## 5. Topology suite
Run the standalone, Sentinel, and Cluster lanes declared in `infra/redis-sdk/`. A version is
Run the standalone, Sentinel, and Cluster lanes declared in `src/adapter/outbound/redis-sdk/compose/`. A version is
certified by the lane passing, not by the version number being newer.
*Why:* failover certainty and cross-slot behaviour are the two things the in-memory fixture cannot
+2 -2
View File
@@ -2031,7 +2031,7 @@ env_keys:
# secret://<acl-account>@<source>/<name> form as the application reference. Unset, scripts run
# as the application account and startup logs a warning saying so. The Compose Redis lanes use
# secret://ca-skeleton-application-advanced@environment/REDIS_LANE_ADVANCED_PASSWORD, a fixture
# account of infra/redis-sdk/acl/lane-fixture-accounts.acl.
# account of compose/redis/acl/lane-fixture-accounts.acl.
property: app.redis.authentication.advanced-credential-reference
owner_module: adapter-outbound-cache-redis
type: string
@@ -2074,7 +2074,7 @@ env_keys:
# <name>. Without the account part the client authenticates as `default`, which a hardened
# Redis turns off. The Compose Redis lanes use
# secret://ca-skeleton-application@environment/REDIS_LANE_APPLICATION_PASSWORD, a fixture
# account of infra/redis-sdk/acl/lane-fixture-accounts.acl.
# account of compose/redis/acl/lane-fixture-accounts.acl.
property: app.redis.authentication.credential-reference
owner_module: adapter-outbound-cache-redis
type: string
+1 -1
View File
@@ -11,7 +11,7 @@
# - prod profile에서 `__LOCAL_DEV_` prefix 발견 시 startup fail
# (feature-secrets-config-source-contract 2026-05-22).
# - prod profile에서 비밀값이 `fixture-`로 시작하면(이 저장소에 적힌 lane fixture 비밀번호 —
# infra/redis-sdk/acl, compose lane의 REDIS_LANE_*) 같은 이유로 startup fail (review 2026-11-03
# compose/redis/acl, compose lane의 REDIS_LANE_*) 같은 이유로 startup fail (review 2026-11-03
# RR-07-04). 비밀값만 본다: 이 파일의 `secret` 행(SecretSourceValidator.CLASSIFIED_SECRETS,
# SecretsClassificationRegistryTest가 1:1로 묶음), 모듈이 기여한 비밀, `secret://…/<VAR>` 참조가
# 가리키는 변수. HOSTNAME·앱 이름 같은 비밀이 아닌 값은 보지 않는다 (review 2026-11-04 RR2-04-01).
+1 -1
View File
@@ -131,7 +131,7 @@ status: active
between them and is claimed again by a new request is deleted while that request runs, and
the next request with the key runs the work a second time (re-review 2026-11-04 RR4-03-02).
The program below deletes the key only while its `state` is `ABANDONED`. The application
accounts are denied `EVAL` (`infra/redis-sdk/acl/README.md`), so load it and run it by the
accounts are denied `EVAL` (`compose/redis/acl/README.md`), so load it and run it by the
digest `SCRIPT LOAD` prints, as the service runs its own scripts:
<!-- runbook-redis: idempotency-delete-abandoned -->
+1 -1
View File
@@ -50,7 +50,7 @@ status: stub
- 의존성 지연이 근본 원인이면 해당 의존성 오너에게 escalate
- 종료 예산은 차례로 더한 값이다: 웹 drain(`APP_SERVER_SHUTDOWN_TIMEOUT`, 기본 30s)이 끝난 뒤 async 대기 19s,
합계 49s에 preStop(5s)과 여유를 더한다. k8s `terminationGracePeriodSeconds`가 이보다 작으면(예: 기본 30s)
async 대기 중 SIGKILL이다. compose는 60s(`docker-compose.yml` `stop_grace_period`, 합계는
async 대기 중 SIGKILL이다. compose는 60s(`compose.yaml` `stop_grace_period`, 합계는
`DeveloperExperienceContractTest`가 검사). 정합 이슈면 플랫폼/런타임 오너에게 escalate
## 6. Recovery / Verification
+3 -2
View File
@@ -73,7 +73,7 @@
|---|---|---|---|---|
| B-12 | JWT 모드에서 `APP_SECURITY_JWT_AUDIENCE` 필수(빈 값 거부, `${...}`가 안 풀린 값도 없는 값으로 봄). 토큰 `aud`가 목록 중 하나를 담아야 통과. `resource_access` role은 audience에 적은 client 것만 읽는다(realm role은 그대로) | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required`(exit 코드 확인 못 함). `.env.example`이 `APP_SECURITY_JWT_AUDIENCE=`(빈 값)를 싣고 있다. 다른 client의 role에 기대던 권한이 사라짐 | client id를 쉼표로 넣는다. 다른 client role로 권한을 받던 사용자가 있는지 IdP에서 확인 | `34565130`(필수·role), `1400dc15`(안 풀린 `${...}`) · `src/adapter/inbound/web/.../auth/JwtDecoderConfig.java`, `.../JwtToAuthenticatedPrincipalConverter.java`, `.../settings/SecuritySettings.java` |
| B-13 | `app.security.*` strict 바인딩: 접두어 아래 오타 키, 또는 설정·placeholder 어디에도 쓰이지 않는 `APP_SECURITY_*` 환경 변수가 기동을 막는다 | 기동 실패(메시지는 `StrictSettingsBinder`가 키 이름을 담아 냄, 정확한 문구 확인 못 함) | 쓰지 않는 `APP_SECURITY_*` 변수를 지운다 | `5786126c` · `SecuritySettings.bind`, `src/adapter/outbound/support/.../StrictSettingsBinder.java` |
| B-14 | prod 프로필에서 `fixture-`로 시작하는 비밀값을 거부(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>` 참조 대상. `HOSTNAME`·앱 이름 같은 비밀 아닌 값은 보지 않는다 — RR2-04-01). Redis ACL fixture 파일 이름 변경: `infra/redis-sdk/acl/all-accounts.acl` → `lane-fixture-accounts.acl` | prod 기동 실패, 요약 `prod secret/config-source contract is invalid`(exit 78). 옛 ACL 경로를 mount하던 compose는 파일 없음 | prod 값을 진짜 비밀로 바꾼다. compose의 ACL 경로를 새 이름으로. Redis SDK admin 계정(`RedisAccountContribution`)을 조립했다면 그 변수를 `static` `RequiredProductionSecrets` bean으로도 낸다(코드에 든 참조는 검사가 보지 않는다, RR3-04-03, `src/adapter/outbound/redis-sdk/README.md`) | `bbe944bd` · `src/app-bootstrap/.../runtime/SecretSourceValidator.java`, `docs/registries/secrets-classification.yaml` |
| B-14 | prod 프로필에서 `fixture-`로 시작하는 비밀값을 거부(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>` 참조 대상. `HOSTNAME`·앱 이름 같은 비밀 아닌 값은 보지 않는다 — RR2-04-01). Redis ACL fixture 파일 이름 변경: `infra/redis-sdk/acl/all-accounts.acl` → `lane-fixture-accounts.acl`(폴더는 지금 `compose/redis/acl/`, B-51) | prod 기동 실패, 요약 `prod secret/config-source contract is invalid`(exit 78). 옛 ACL 경로를 mount하던 compose는 파일 없음 | prod 값을 진짜 비밀로 바꾼다. compose의 ACL 경로를 새 이름으로. Redis SDK admin 계정(`RedisAccountContribution`)을 조립했다면 그 변수를 `static` `RequiredProductionSecrets` bean으로도 낸다(코드에 든 참조는 검사가 보지 않는다, RR3-04-03, `src/adapter/outbound/redis-sdk/README.md`) | `bbe944bd` · `src/app-bootstrap/.../runtime/SecretSourceValidator.java`, `docs/registries/secrets-classification.yaml` |
| B-15 | 기동 rule이 모든 singleton보다 먼저 돈다(`StartupRuleRunner`가 `BeanFactoryPostProcessor`). `StartupRule`과 `RequiredProductionSecrets` bean은 `static @Bean`이고 `Environment`, bean factory, static 무인자 `RequiredProductionSecrets`의 `ObjectProvider`만 받아야 한다. 두 타입의 클래스는 `@Value`·`@Autowired`·`@Inject`·`@Resource` 멤버, `@PostConstruct`·`@PreDestroy`, `@ConfigurationProperties`를 가질 수 없다(post-processor보다 먼저 만들어져 비어 있게 된다, RR2-04-03) | non-static `@Bean`이거나 다른 bean을 받으면 기동 실패 `startup rule or secret list '<이름>' created [<bean>] while creating it ... Declare the rule with a static @Bean method ...`, 위 멤버가 있으면 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one: [...]`(둘 다 exit 78, 둘 다 모든 프로필. runner가 rule과 비밀 목록을 프로필과 무관하게 먼저 만들어, 인터페이스 타입 `@Bean`이 돌려준 실제 클래스까지 본다, RR3-04-01) | rule 선언을 `static`으로, 인자를 위 셋으로 줄인다. 값은 `violations(Environment)`가 받는 `Environment`에서 읽는다. 다른 bean이 필요한 검사는 rule이 아니라 일반 bean으로 둔다 | `34565130`, `bbe944bd` · `src/adapter/outbound/support/.../startup/StartupRule.java`, `StartupRuleRunner.java` |
| B-16 | 권한 가드(새 `PermissionEnforcementGuard`): `@SystemInvoked` 유스케이스가 bean이면 기동 실패. `@RequiresPermission`을 단 bean에 적용되는 advisor가 없어도 기동 실패. ArchUnit `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`, `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`, `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES` 추가, 새 표시 `@SystemCaller` | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). `@SystemCaller`가 아닌 inbound adapter가 그 유스케이스를 부르거나, 사용자 전송(controller 등)이 `@SystemCaller` bean을 직접·중간 클래스를 거쳐·그 작업이 구현하는 프로젝트 인터페이스로 부르면 architectureTest 실패. `@SystemCaller` 클래스가 `Runnable`·`ApplicationRunner` 같은 프로젝트 밖 타입을 구현·상속해도 실패. 설정(`@Configuration`)은 웹 bean(`WebMvcConfigurer`·CORS 설정·controller bean)과 handler bean을 함께 등록해도 사용자 전송으로 세지 않지만, 요청 처리기 타입(함수형 route·data fetcher·interceptor)에 의존하면 사용자 전송으로 센다. 처리 코드를 설정에 직접 쓰든, 다른 클래스의 메서드를 참조해 등록만 하든 같다. 설정 안에 중첩된 클래스는 설정용 타입(configurer·registry·CORS 설정·`RequestMethod`)에만 의존할 때를 빼고 다른 클래스처럼 사용자 전송 타입으로 판정한다(중첩된 JAX-RS 자원·`@ServerEndpoint`도 잡힌다). STOMP inbound channel interceptor(`ChannelInterceptor`·`ExecutorChannelInterceptor`)도 사용자 전송 타입이자 요청 처리기 타입이다. 사용자 전송 패키지 밖에 둔 interceptor, 설정에 중첩한 interceptor(익명 클래스 포함), interceptor를 구현한 설정이 `@SystemCaller`에 닿거나, interceptor를 `@Bean`으로 내놓는 설정이 `@SystemCaller` bean도 만들면 실패한다(2026-11-07 전에는 STOMP 헤더 타입을 읽는 interceptor만 잡혔다). record·enum이 언어로 받는 상위 타입(`Record`·`Enum` 등)과 예외 클래스는 프로젝트 밖 상위 타입으로 세지 않는다 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 스케줄러에 넘기거나, 메시지 handler·예약 작업이면 그 클래스에 `@SystemCaller`를 달고 생성자에서 `new`로 만든다. 예약 작업은 서비스 leaf의 `..adapter.inbound.scheduler..` 패키지에 둔다. 세 경로와 두는 곳은 매뉴얼 07장 「시스템이 부르는 쓰기」(handler 작업 순서는 09장 「소비」 4단계). "지금 실행" endpoint가 필요하면 `@RequiresPermission` 유스케이스를 따로 만든다. 작업을 task scheduler에 직접 등록하던 코드는 작업이 `Runnable`을 구현하는 대신 등록하는 곳에서 `job::run`을 넘긴다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. STOMP channel interceptor 등록도 같다. `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd`, r9 · `src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java`, `src/application-core/.../security/SystemInvoked.java`, `SystemCaller.java` |
| B-17 | `IntegrationEventDraft`: `eventId`·`causationId`는 소문자 UUIDv7만. ArchUnit `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`: `new IntegrationEventDraft<>(...)` 금지, `IntegrationEventDrafts.draft(...)`만 | 이벤트를 만드는 쓰기 요청이 `IllegalArgumentException: eventId must be a canonical lower-case UUIDv7...`로 실패. architectureTest 실패 | event id를 UUIDv7로 만든다(예: sample `UuidOutboxEventIdFactory`가 `UuidCreator.getTimeOrderedEpochPlus1()`). draft는 헬퍼로 만든다. tenant가 없는 이벤트는 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`) | `1400dc15`, `bbe944bd` · `src/application-core/.../messaging/event/IntegrationEventDraft.java`, `IntegrationEventDrafts.java` |
@@ -133,6 +133,7 @@
|---|---|---|---|---|
| B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | `ab5982e9` |
| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | 커밋 「쓰지 않는 파일과 운영 인프라 파일을 지운다」 |
| B-51 | compose 정리. 루트 `docker-compose.yml`·`docker-compose.local.yml`·`docker-compose.infra.yml`을 개발 환경 `compose.yaml` 하나로 합쳤다(app은 `local` 런타임, 뒷단 서비스는 capability profile `jpa`·`redis`·`kafka`·`mongo`·`objectstorage`·`auth`·`mail`). 보조 파일은 `compose/`(keycloak realm·entrypoint, minio init, Redis ACL, mailpit 인증서 폴더). 테스트 lane fixture는 그 lane을 가진 leaf로 옮겼다: `docker-compose.dev.yml`·`docker-compose.prod-smoke.yml`·`docker-compose.tls.yml`·fileserver overlay·smoke 스크립트·스키마 적용 스크립트·lane 계약 JSON(`src/config/runtime/compose-profile-contracts.json`) → `src/app-bootstrap/compose-lanes/`, Redis topology compose → `src/adapter/outbound/redis-sdk/compose/`, NFS compose → `src/adapter/outbound/fileserver/compose/nfs/`. `infra/`는 없어졌다. lane 계약의 `composeProfile`(문자열)은 `composeProfiles`(목록)로 바뀌었고 `appMemoryLimit`이 생겼다. smoke는 lane 중 컨테이너가 재시작하거나 메모리로 죽으면 실패한다. `scripts/bootstrap-local.sh`는 인자를 받지 않는다 | `docker compose -f docker-compose.yml -f docker-compose.local.yml …`을 쓰던 스크립트·문서가 "no such file"로 실패. 옛 compose 파일에 서비스를 더했으면 수정 대 삭제 충돌. lane 계약을 고쳐 쓰던 서비스는 `composeProfile` 키를 smoke 스크립트가 읽지 않는다 | 명령을 `docker compose …`(루트 `compose.yaml`)와 profile로 바꾼다. 더한 서비스는 `compose.yaml`에 capability profile을 달아 옮기고, lane 전용이면 `src/app-bootstrap/compose-lanes/lane-services.yaml`에 둔다. 경로를 적은 workflow·문서를 위 새 경로로 고친다 | 커밋 「compose 파일을 개발 환경 하나와 lane fixture로 나눈다」 |
## 4. DB 마이그레이션
@@ -175,7 +176,7 @@
- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, grpc V002·V003을 쓴다(sample V8_1은 샘플과 함께 사라졌다, B-49). 파생 서비스가 같은
위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다
(이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다).
- **migration-on-startup=false로 운영하는 서비스**: `infra/postgres/apply-capability-streams.sh`가 바뀌었다(stream을
- **migration-on-startup=false로 운영하는 서비스**: `infra/postgres/apply-capability-streams.sh`(지금 `src/app-bootstrap/compose-lanes/postgres/apply-capability-streams.sh`, B-51)가 바뀌었다(stream을
`/flyway/streams/<name>`에서 먼저 찾음). 운영자가 직접 적용한다.
### 4.2 이 브랜치의 이전 V21(과 3차 수정 전 V20·V22·V11~V13·V8_1·V002·V003)을 적용한 DB
+1 -1
View File
@@ -59,7 +59,7 @@ git worktree remove ~/workspace/<작업 이름>
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절).
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(`docker-compose.dev.yml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`docker-compose.infra.yml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
**push 전에 검증하기.** push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다.
+1
View File
@@ -74,6 +74,7 @@
| 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) |
| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) |
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b |
| 개발 compose 파일 | 저장소 루트에 `compose.yaml` 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 `compose/`에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap `compose-lanes/`, Redis topology → redis-sdk, NFS → fileserver). `docker-compose.dev.yml`은 `dev` 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
| 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 `infra/` 파일도 지운다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
| 샘플 모듈 | `src/sample-portfolio`와 `src/Dockerfile.sample`을 폴더째 지운다. 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.2절 |
+1 -1
View File
@@ -112,7 +112,7 @@ cd src
./gradlew -p optional-platforms releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
cd ..
bash scripts/verify-compose-profile-contracts.sh
bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
```
- 여러 명령으로 된 main job 둘은 그 job의 `run` 줄을 차례로 그대로 돌린다: `integration-main.yml`의 `configuration-cache`(로그에 "Reusing configuration cache."가 있어야 한다), `notification-platform.yml`의 `pr`(main push마다 경로와 상관없이 돈다).
+14 -12
View File
@@ -1,31 +1,33 @@
#!/usr/bin/env bash
# The ordered local start-up: compile, Docker preflight, dependency wait, migrate-and-start, smoke.
#
# scripts/bootstrap-local.sh # the `local` overlay (docker-compose.local.yml)
# scripts/bootstrap-local.sh <profile> # docker-compose.<profile>.yml merged onto docker-compose.yml
# scripts/bootstrap-local.sh
#
# It runs the development stack, compose.yaml at the repository root: the application container in
# the `local` runtime and the PostgreSQL service of the `jpa` profile. Naming a service on the
# command line switches its profile on, so no --profile is needed here.
#
# This was the build-logic `ca.developer-bootstrap` plugin (`./gradlew bootstrap`). Starting
# containers and probing an HTTP endpoint is not a build rule, so it is a script now (review
# 2026-09-24 BUILD-O3-5). The four stages and their order are unchanged: the next stage starts only
# when the previous one succeeded, and the app stage waits for startup Flyway through the compose
# healthcheck before the smoke probe runs.
#
# Until 2026-11-07 it merged docker-compose.yml with docker-compose.local.yml and asked for a `db`
# service neither file had defined since the database moved to a third file, so the documented
# first run stopped at stage 2.
set -euo pipefail
readonly repository_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
readonly profile="${1:-local}"
readonly base_compose="${repository_dir}/docker-compose.yml"
readonly overlay="${repository_dir}/docker-compose.${profile}.yml"
readonly health_endpoint="${BOOTSTRAP_HEALTH_ENDPOINT:-http://localhost:8080/api/healthcheck}"
readonly smoke_timeout_seconds="${BOOTSTRAP_SMOKE_TIMEOUT_SECONDS:-60}"
if [[ ! -f "${overlay}" ]]; then
available="$(cd "${repository_dir}" && ls docker-compose.*.yml 2>/dev/null \
| sed -e 's/^docker-compose\.//' -e 's/\.yml$//' | tr '\n' ' ')"
echo "bootstrap: '${profile}' names no overlay; expected $(basename "${overlay}") beside" \
"docker-compose.yml. Available: ${available:-none}" >&2
if [[ $# -gt 0 ]]; then
echo "bootstrap: takes no arguments; the stack is compose.yaml. Backing services by profile:" \
"docker compose --profile <profile> up -d --wait (see the head of compose.yaml)" >&2
exit 64
fi
compose=(docker compose -f "${base_compose}" -f "${overlay}")
compose=(docker compose -f "${repository_dir}/compose.yaml")
echo "bootstrap 1/4: compiling the default application composition"
(cd "${repository_dir}/src" && ./gradlew :app-bootstrap:compileTestJava --console=plain)
@@ -35,7 +37,7 @@ if ! docker info >/dev/null 2>&1; then
exit 69
fi
echo "bootstrap 2/4: starting the ${profile} PostgreSQL dependency and waiting for readiness"
echo "bootstrap 2/4: starting the PostgreSQL dependency and waiting for readiness"
"${compose[@]}" up -d --wait db
echo "bootstrap 3/4: building and starting the app; startup Flyway finishes before health is ready"
+59 -18
View File
@@ -13,6 +13,8 @@
# compared with the lane's expectedCapabilitiesOn and expectedPersistenceVendor;
# 4. every one-shot the lane declares, each of which must exit zero — a missing or skipped
# required client is a lane failure, not a lane that had nothing to check;
# 4a. no container of the lane restarted or was killed for memory — a container that died and came
# back between the checks above would otherwise leave every one of them green;
# 5. sanitized evidence;
# 6. teardown scoped to this project alone, on success and failure alike, after the logs are
# collected rather than before.
@@ -22,7 +24,7 @@
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CONTRACTS="${REPO_ROOT}/src/config/runtime/compose-profile-contracts.json"
CONTRACTS="${REPO_ROOT}/src/app-bootstrap/compose-lanes/compose-profile-contracts.json"
EVIDENCE_ROOT="${REPO_ROOT}/src/app-bootstrap/build/evidence/runtime-smoke"
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
# Compose project names accept lowercase alphanumerics, hyphens and underscores only, so the run id
@@ -32,7 +34,7 @@ PROJECT_RUN_ID="$(tr '[:upper:]' '[:lower:]' <<<"${RUN_ID}")"
# The lanes boot the qualification image: the application with every capability module on the
# classpath (src/Dockerfile COMPOSITION, app-bootstrap qualificationBootJar). The default image is
# the composition a service ships and carries none of them, so a lane that switches JPA or Kafka on
# would have nothing to switch. docker-compose.yml passes this to the build and puts it in the tag.
# would have nothing to switch. compose.yaml passes this to the build and puts it in the tag.
export COMPOSITION=qualification
# Every capability is on while its module is present, so each lane starts from all of them off and
@@ -79,6 +81,9 @@ for tool in jq docker; do
done
[[ -r "${CONTRACTS}" ]] || { echo "missing ${CONTRACTS}" >&2; exit 78; }
# The lane-only TLS overlay's keypair directory (src/app-bootstrap/compose-lanes/tls.yaml).
LANE_POSTGRES_TLS="${REPO_ROOT}/src/app-bootstrap/compose-lanes/postgres/tls"
# ---- per-lane state, cleaned up by the trap ---------------------------------
PROJECT=""
LANE_TMP=""
@@ -109,14 +114,14 @@ cleanup_lane() {
fi
[[ -n "${LANE_TMP}" && -d "${LANE_TMP}" ]] && rm -rf "${LANE_TMP}"
# .env.lane is gone — the lane's values live in the generated overlay now — but a file left by an
# older revision of this script would still be read by the local overlay's env_file list.
rm -f "${REPO_ROOT}/src/.env.lane" "${REPO_ROOT}/infra/keycloak/secrets/graphql-smoke-client-secret"
# older revision of this script would still be read by an env_file list of an older stack.
rm -f "${REPO_ROOT}/src/.env.lane" "${REPO_ROOT}/compose/keycloak/secrets/graphql-smoke-client-secret"
# The lane keypair, including the CA's private half. A certificate that outlives the run it was
# made for is a credential nobody is tracking.
rm -f "${REPO_ROOT}"/infra/postgres/tls/ca.key "${REPO_ROOT}"/infra/postgres/tls/ca.crt \
"${REPO_ROOT}"/infra/postgres/tls/ca.srl "${REPO_ROOT}"/infra/postgres/tls/server.key \
"${REPO_ROOT}"/infra/postgres/tls/server.crt "${REPO_ROOT}"/infra/postgres/tls/server.csr \
"${REPO_ROOT}"/infra/mailpit/tls/server.key "${REPO_ROOT}"/infra/mailpit/tls/server.crt
rm -f "${LANE_POSTGRES_TLS}"/ca.key "${LANE_POSTGRES_TLS}"/ca.crt \
"${LANE_POSTGRES_TLS}"/ca.srl "${LANE_POSTGRES_TLS}"/server.key \
"${LANE_POSTGRES_TLS}"/server.crt "${LANE_POSTGRES_TLS}"/server.csr \
"${REPO_ROOT}"/compose/mailpit/tls/server.key "${REPO_ROOT}"/compose/mailpit/tls/server.crt
return "${status}"
}
@@ -140,9 +145,8 @@ random_key() { head -c 32 /dev/urandom | base64 | tr -d '\n'; }
run_lane() {
local lane_json="$1"
local id profile runtime
local id runtime profile
id="$(jq -r '.id' <<<"${lane_json}")"
profile="$(jq -r '.composeProfile // empty' <<<"${lane_json}")"
runtime="$(jq -r '.springRuntime' <<<"${lane_json}")"
PROJECT="casmoke-${id}-${PROJECT_RUN_ID}"
@@ -161,10 +165,14 @@ run_lane() {
file="$(jq -r --arg k "${key}" '.composeFiles[$k]' "${CONTRACTS}")"
LANE_ARGS+=(-f "${REPO_ROOT}/${file}")
done < <(jq -r '.files[]' <<<"${lane_json}")
[[ -n "${profile}" ]] && LANE_ARGS+=(--profile "${profile}")
# The development stack's backing services carry capability profiles and the lane-only services
# their own, so a lane enables several. The list is the lane's, never a guess from its name.
while read -r profile; do
[[ -n "${profile}" ]] && LANE_ARGS+=(--profile "${profile}")
done < <(jq -r '.composeProfiles[]' <<<"${lane_json}")
# A fresh client secret per run, mode 0600, removed on teardown. The realm references it by name.
local secret_dir="${REPO_ROOT}/infra/keycloak/secrets"
local secret_dir="${REPO_ROOT}/compose/keycloak/secrets"
local secret_file="${secret_dir}/graphql-smoke-client-secret"
mkdir -p "${secret_dir}"
local client_secret; client_secret="$(random_secret)"
@@ -177,7 +185,7 @@ run_lane() {
# a private key in Git. The host name matters — the prod runtime connects with sslmode=verify-full,
# which checks the certificate against the name it dialled, so a certificate for anything but `db`
# fails exactly as a redirected connection would. That is the check, working.
local tls_dir="${REPO_ROOT}/infra/postgres/tls"
local tls_dir="${LANE_POSTGRES_TLS}"
if jq -e '.files | index("tls")' <<<"${lane_json}" >/dev/null; then
mkdir -p "${tls_dir}"
(
@@ -205,7 +213,7 @@ run_lane() {
# Same rule as the PostgreSQL one above and for the same reason: the notification platform's
# transport type has no plaintext member, so a relay without a certificate is one the platform
# cannot be configured to talk to. Generated per run, removed on teardown.
local mail_tls="${REPO_ROOT}/infra/mailpit/tls"
local mail_tls="${REPO_ROOT}/compose/mailpit/tls"
if jq -e '.services | index("mailpit")' <<<"${lane_json}" >/dev/null; then
mkdir -p "${mail_tls}"
(
@@ -232,7 +240,7 @@ run_lane() {
# interpolation reads the process environment and the project .env file, never a service's
# env_file. So the application got the generated password and the database got the literal
# default, and no lane whose overlay did not happen to restate the value could ever authenticate.
# shared-infra-local passed only because the local overlay restates it, which made the dev lane's
# shared-infra-local passed only because the local overlay (now compose.yaml) restated it, which made the dev lane's
# failure look like a dev-specific problem rather than the general one it is.
export POSTGRES_DB=ca_skeleton
export APP_DATASOURCE_USERNAME=ca_skeleton
@@ -323,7 +331,7 @@ run_lane() {
# The lane's own settings go into a generated overlay rather than into that file.
#
# env_file lists merge across overlays and the later file wins, so the developer's optional
# src/.env — declared by the local overlay, after the base — silently overrode the lane's values.
# src/.env — declared by the local overlay (now compose.yaml) — silently overrode the lane's values.
# local-messaging started Kafka, set APP_MESSAGING_BROKER=kafka, and was refused by the dependency
# validator for a broker it had supplied, because an empty value from a file nobody mentioned won
# the merge. An `environment:` block beats every env_file regardless of order, so the lane's
@@ -333,6 +341,10 @@ run_lane() {
# Written as a function, because a handoff lane rewrites it between phases: the same project and
# the same database, with the application recreated under a different activation environment.
local lane_overlay="${LANE_TMP}/lane-overrides.yml"
# The application's memory limit, when the lane needs more than the development stack's 512m.
# Only the lane that boots every capability at once does (the contract's appMemoryLimit says why).
local memory_limit
memory_limit="$(jq -r '.appMemoryLimit // empty' <<<"${lane_json}")"
write_lane_overlay() {
local phase_override="${1:-{\}}"
(
@@ -340,6 +352,10 @@ run_lane() {
{
echo "services:"
echo " app:"
if [[ -n "${memory_limit}" ]]; then
echo " mem_limit: ${memory_limit}"
echo " memswap_limit: ${memory_limit}"
fi
echo " environment:"
local entry
for entry in "${lane_environment[@]}"; do
@@ -550,13 +566,38 @@ run_lane() {
return 1
fi
# 4a. No container of the lane restarted and none was killed for memory.
#
# The application runs with `restart: unless-stopped`, so a container the kernel killed for
# exceeding its memory limit came back on its own. all-adapters did exactly that for a long time
# and failed only when the kill happened to land on a smoke request; every other run reported
# green over a container that had died and restarted under it (integration-r9, 2026-11-07). The
# checks above all ask the application a question, and a restarted application answers them, so
# the restart itself has to be the failure. The peak memory is recorded beside it, so a lane that
# is close to its limit is visible before it crosses it.
local container restarted=""
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app cat /sys/fs/cgroup/memory.peak \
>"${LANE_EVIDENCE}/app-memory-peak-bytes.txt" 2>/dev/null || true
while read -r container; do
[[ -z "${container}" ]] && continue
docker inspect --format '{{.Name}} restarts={{.RestartCount}} oomKilled={{.State.OOMKilled}}' \
"${container}" >>"${LANE_EVIDENCE}/restarts.txt"
done < <(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" ps -a -q)
restarted="$(grep -v ' restarts=0 oomKilled=false$' "${LANE_EVIDENCE}/restarts.txt" || true)"
if [[ -n "${restarted}" ]]; then
echo "${id}: a container restarted or was killed for memory during the lane:" >&2
echo "${restarted}" >&2
return 1
fi
# 5. the manifest ties the evidence to the exact stack that produced it
jq -n \
--arg lane "${id}" --arg run "${RUN_ID}" --arg project "${PROJECT}" \
--arg runtime "${runtime}" --arg profile "${profile}" \
--arg runtime "${runtime}" \
--argjson profiles "$(jq '.composeProfiles' <<<"${lane_json}")" \
--argjson services "$(jq '.services' <<<"${lane_json}")" \
'{lane:$lane, runId:$run, project:$project, springRuntime:$runtime,
composeProfile:(if $profile=="" then null else $profile end), services:$services}' \
composeProfiles:$profiles, services:$services}' \
>"${LANE_EVIDENCE}/manifest.json"
echo "== ${id}: passed"
+19 -9
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# The static half of the Compose contract: every lane renders, and renders exactly what it claims.
#
# Seven things are checked, and each exists because assuming it cost something:
# Nine things are checked, and each exists because assuming it cost something:
#
# 1. the Compose version, because `!override` is what stops the dev overlay's tmpfs merging with
# the base's and colliding with a bind mount, and it needs 2.24.4;
@@ -22,12 +22,15 @@
# lanes ran Redis open and the application anonymous, and the two startup warnings that trade
# prints failed the "startup is silent" check of every such lane (r3-J). Lowering that warning
# would hide the same trade in production; the lane has to look like a deployment instead.
# 8. a lane's appMemoryLimit, when it has one, is a Compose memory size, because the smoke wrapper
# writes it into the application's mem_limit and a malformed one fails only at `up`.
# 9. the Keycloak realm artifact carries no key Keycloak refuses (below the lane loop).
#
# Static only. Nothing starts here; scripts/run-compose-runtime-smoke.sh owns that.
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CONTRACTS="${REPO_ROOT}/src/config/runtime/compose-profile-contracts.json"
CONTRACTS="${REPO_ROOT}/src/app-bootstrap/compose-lanes/compose-profile-contracts.json"
FAILURES=0
fail() { echo " FAIL: $*" >&2; FAILURES=$((FAILURES + 1)); }
@@ -118,7 +121,6 @@ lane_count="$(jq '.lanes | length' "${CONTRACTS}")"
for index in $(seq 0 $((lane_count - 1))); do
lane="$(jq -c ".lanes[${index}]" "${CONTRACTS}")"
id="$(jq -r '.id' <<<"${lane}")"
profile="$(jq -r '.composeProfile // empty' <<<"${lane}")"
runtime="$(jq -r '.springRuntime' <<<"${lane}")"
expected="$(jq -r '.services | sort | join(",")' <<<"${lane}")"
@@ -130,7 +132,9 @@ for index in $(seq 0 $((lane_count - 1))); do
done < <(jq -r '.files[]' <<<"${lane}")
profile_args=()
[[ -n "${profile}" ]] && profile_args=(--profile "${profile}")
while read -r profile; do
[[ -n "${profile}" ]] && profile_args+=(--profile "${profile}")
done < <(jq -r '.composeProfiles[]' <<<"${lane}")
# 2. exact service set
# stderr goes to a file rather than into the list. It used to be merged with `2>&1`, so Compose's
@@ -223,20 +227,26 @@ for index in $(seq 0 $((lane_count - 1))); do
done < <(redis_authentication_problems "${lane}" "${model}")
fi
# 8. the lane's own memory limit, when it sets one.
memory_limit="$(jq -r '.appMemoryLimit // empty' <<<"${lane}")"
if [[ -n "${memory_limit}" && ! "${memory_limit}" =~ ^[1-9][0-9]*[kmg]$ ]]; then
fail "${id}: appMemoryLimit '${memory_limit}' is not a Compose memory size such as 1g"
fi
[[ ${FAILURES} -eq 0 ]] && echo "${id}: ${expected} @ ${runtime}"
done
# 8. the Keycloak realm artifact deserializes into Keycloak's own representation.
# 9. the Keycloak realm artifact deserializes into Keycloak's own representation.
#
# Keycloak rejects unknown fields rather than ignoring them, so one annotation key anywhere in the
# tree fails the whole import, the container exits 1, and every lane that needs an identity provider
# fails on Keycloak instead of on what it was testing. This cost two lane runs to find, once for
# `_comment` on the realm and once for `_flowComment` on a client, because the second was invisible
# until the first was fixed. Rationale for that artifact lives in infra/keycloak/README.md.
realm="${REPO_ROOT}/infra/keycloak/realms/ca-skeleton-realm.json"
# until the first was fixed. Rationale for that artifact lives in compose/keycloak/README.md.
realm="${REPO_ROOT}/compose/keycloak/realms/ca-skeleton-realm.json"
if [[ -f "${realm}" ]]; then
if ! jq empty "${realm}" >/dev/null 2>&1; then
fail "infra/keycloak/realms/ca-skeleton-realm.json is not valid JSON"
fail "compose/keycloak/realms/ca-skeleton-realm.json is not valid JSON"
else
annotations="$(jq -r '[paths(scalars, objects, arrays) | .[-1] | select(type == "string") | select(startswith("_"))] | unique | join(", ")' "${realm}")"
if [[ -n "${annotations}" ]]; then
@@ -249,4 +259,4 @@ if [[ ${FAILURES} -gt 0 ]]; then
echo "verify-compose-profile-contracts: ${FAILURES} lane(s) do not match the contract" >&2
exit 1
fi
echo "verify-compose-profile-contracts: all ${lane_count} lanes match src/config/runtime/compose-profile-contracts.json"
echo "verify-compose-profile-contracts: all ${lane_count} lanes match src/app-bootstrap/compose-lanes/compose-profile-contracts.json"
+2 -2
View File
@@ -155,8 +155,8 @@ APP_REDIS_TIMEOUT_SCRIPT=1s
# reads the password from <VARIABLE> and authenticates as <acl-account>. With the application
# reference empty and anonymous access not accepted, the application refuses to start while Redis
# is on; with the advanced one empty, scripts run as the application account and startup warns. The
# Compose Redis lanes connect as the fixture accounts of infra/redis-sdk/acl/lane-fixture-accounts.acl (the
# Redis comment in src/config/runtime/compose-profile-contracts.json).
# Compose Redis lanes connect as the fixture accounts of compose/redis/acl/lane-fixture-accounts.acl (the
# Redis comment in src/app-bootstrap/compose-lanes/compose-profile-contracts.json).
APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false
APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE=
+10 -9
View File
@@ -46,10 +46,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
### Local bootstrap
`scripts/bootstrap-local.sh [profile]`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
`scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 `./gradlew bootstrap`, 리뷰
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 base/local Compose 조합이 소유하며, app startup Flyway가
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을
함께 검사합니다.
@@ -296,8 +296,9 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
### Compose와 런타임 스모크
- **Docker Compose 최소 버전 `2.24.4`.** SSOT는 `src/config/runtime/compose-profile-contracts.json`
이고, 정본 스크립트가 검증합니다.
- **Docker Compose 최소 버전 `2.24.4`.** SSOT는 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`
이고, 정본 스크립트가 검증합니다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있습니다.
- 진입점은 둘뿐이고, 그 둘만이 증거입니다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
초록으로 보고됩니다.
@@ -305,9 +306,9 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
# 정적: 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
# 동적: 계약의 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가 통과했다는 증거가 아닙니다.
@@ -532,11 +533,11 @@ migration/vendor 계약의 증거로 사용하지 않습니다. 멱등성 provid
`disabled`(기본)나 `redis`로 둡니다. `postgresql`은 H2 data source에서 기동을 거부합니다.
`dev` 를 호스트에서 띄우려면(`SPRING_PROFILES_ACTIVE=dev`) PostgreSQL 이 필요합니다.
`docker-compose.local.yml` 의 `db` 서비스가 루프백(`127.0.0.1:5433`)에만 게시하며, 이 주소가
`compose.yaml` 의 `db` 서비스(`jpa` profile)가 루프백(`127.0.0.1:5433`)에만 게시하며, 이 주소가
아래 `APP_DATASOURCE_URL` 의 커밋된 기본값입니다. 저장소 루트에서 실행합니다.
```bash
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --wait db
docker compose up -d --wait db
```
컨테이너로 띄우는 `scripts/bootstrap-local.sh` 경로는 이 호스트 포트를 쓰지 않습니다. compose 가 app
+1 -1
View File
@@ -130,7 +130,7 @@ be silently skipped when selected.
Two real-server lanes. `redisContainerContractTest` (integration category, in `integrationCheck` only —
not in this leaf's `mainCheck` too, which ran it twice per push to main) starts its own Redis with Testcontainers — the `redis` image of
`config/testing/container-images.properties`, loading `infra/redis-sdk/acl/lane-fixture-accounts.acl` — and
`config/testing/container-images.properties`, loading `compose/redis/acl/lane-fixture-accounts.acl` — and
runs `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest` and
`LiveRedisIdempotencyStoreContractTest` (the `application-core` port contracts the in-memory fakes
also pass), `LiveRedisSemanticPortsTest` and `LiveRedisSemanticScriptAclProbeTest`; a skip fails it
@@ -69,14 +69,15 @@ redisTopologyLane {
// needs coordinates of a topology someone else started — so until this lane existed the Redis
// adapters' port contracts reached a real server in no stage, and the fake and the adapter could hide
// the same defect (05-02, 05-03). The image is config/testing/container-images.properties' `redis`,
// and the ACL file is infra/redis-sdk's own, so the accounts and their rights are the standalone
// and the ACL file is the one the development stack and the redis-sdk topologies share
// (compose/redis/acl), so the accounts and their rights are the standalone
// topology's. Integration category, so integrationCheck runs it — integration-main.yml's
// `integration-check` job, on every push to main and nightly. It is deliberately not in this leaf's
// mainCheck as well: `main-check` and `integration-check` are two jobs of the same workflow run, so a
// lane in both started a second Redis container and ran every live contract twice per push without
// covering anything the first run did not (found while fixing review 2026-11-03). Sentinel, cluster
// and TLS remain the topology lane's.
def redisAclDirectory = rootProject.projectDir.parentFile.toPath().resolve('infra/redis-sdk/acl').toFile()
def redisAclDirectory = rootProject.projectDir.parentFile.toPath().resolve('compose/redis/acl').toFile()
strictTestLanes {
lane('redisContainerContractTest') {
integration()
@@ -12,7 +12,7 @@ import org.testcontainers.utility.MountableFile;
* One Redis server for the container lane ({@code redisContainerContractTest}), so the live
* contracts run against a real server without an external topology (review 2026-11-01 05-16).
*
* <p>The server is the standalone topology of {@code infra/redis-sdk}: the image is the {@code
* <p>The server is the standalone topology of {@code redis-sdk/compose}: the image is the {@code
* redis} entry of {@code config/testing/container-images.properties} (handed to every test JVM as
* {@code ca.test.image.redis}), and the ACL file is the one that topology loads, so the default
* user is off and the application and advanced accounts carry the same rights they carry there. A
@@ -7,11 +7,11 @@
#
# Opt in with FILESERVER_NFS_TESTS=true; the default test run does not start this.
#
# docker compose -f infra/fileserver/nfs/compose.yml up -d
# docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d
# FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test
#
# To exercise the ambiguity paths:
# docker compose -f infra/fileserver/nfs/compose.yml restart nfs-server # stale handles
# docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml restart nfs-server # stale handles
# docker network disconnect fileserver-nfs <client> # lost responses
services:
@@ -49,7 +49,7 @@ services:
mount -t nfs4 -o hard,timeo=50,retrans=2 nfs-server:/ /mnt/fileserver &&
tail -f /dev/null"
volumes:
- ../../..:/workspace:ro
- ../../../../../..:/workspace:ro
networks:
- fileserver-nfs
@@ -14,7 +14,7 @@ import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
*
* <p>These scenarios cannot be reproduced on a local filesystem, so they are gated rather than
* quietly skipped: a green default run must never be mistaken for network-filesystem certification.
* The environment is defined in {@code infra/fileserver/nfs/compose.yml}.
* The environment is defined in {@code src/adapter/outbound/fileserver/compose/nfs/compose.yml}.
*/
@EnabledIfEnvironmentVariable(named = NfsTestEnvironment.ENABLE_FLAG, matches = "true")
class NfsAmbiguityIntegrationTest {
+1 -1
View File
@@ -120,7 +120,7 @@ release the `status`, `excludedProfiles` and `limitations` beside it were measur
`-PobjectStorageMinioImage=<registry>/<repo>@sha256:<evidence digest>`. A value that does not end
in the evidence digest is refused: a different build is a new measurement, made by re-running the
lanes and rewriting the evidence file (image and findings together).
- The local compose runtime (`docker-compose.infra.yml`, `LOCAL_MINIO_IMAGE`) uses the same digest.
- The local compose runtime (`compose.yaml`, and the compose lanes' smoke client in `src/app-bootstrap/compose-lanes/lane-services.yaml`; `LOCAL_MINIO_IMAGE`) uses the same digest.
`ComposeMinioImageMatchesEvidenceTest` (leaf `test`) fails when the compose default and the
evidence disagree; change both together.
- The contract lane also runs `MinioS3ManagedObjectProviderContractTest`: the S3 adapter itself under
@@ -96,16 +96,21 @@ dependencies {
def objectStorageReadinessRegistry = rootProject.projectDir.parentFile.toPath()
.resolve('docs/registries/object-storage-readiness.yaml').toFile()
// The local compose MinIO must be the image the evidence measured (review 05-09);
// ComposeMinioImageMatchesEvidenceTest compares the two.
def localComposeFile = rootProject.projectDir.parentFile.toPath()
.resolve('docker-compose.infra.yml').toFile()
// ComposeMinioImageMatchesEvidenceTest compares the two. The development stack runs the server and
// the compose lanes' smoke client runs the same image; YAML anchors do not cross files, so each file
// carries its own default and both are compared.
def repositoryRootForCompose = rootProject.projectDir.parentFile.toPath()
def localComposeFiles = [
repositoryRootForCompose.resolve('compose.yaml').toFile(),
repositoryRootForCompose.resolve('src/app-bootstrap/compose-lanes/lane-services.yaml').toFile(),
]
tasks.named('test') {
inputs.file(objectStorageReadinessRegistry)
.withPathSensitivity(PathSensitivity.RELATIVE)
systemProperty 'objectstorage.readiness.registry', objectStorageReadinessRegistry.absolutePath
inputs.file(localComposeFile)
inputs.files(localComposeFiles)
.withPathSensitivity(PathSensitivity.RELATIVE)
systemProperty 'objectstorage.compose.file', localComposeFile.absolutePath
systemProperty 'objectstorage.compose.files', localComposeFiles*.absolutePath.join(File.pathSeparator)
}
// A mirror of the measured MinIO digest, for when the origin registry stops serving it (review
@@ -2,9 +2,11 @@ package dev.caskeleton.adapter.outbound.objectstorage.qualification;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Optional;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
@@ -13,12 +15,14 @@ import org.junit.jupiter.api.Test;
/**
* The local compose MinIO is the image the lanes measured. Compose cannot read the evidence JSON,
* so this is the one check that keeps the two references from drifting apart again (review 05-09:
* four copies, two of them disagreeing). The build declares the compose file as this task's input.
* so this is the one check that keeps the references from drifting apart again (review 05-09: four
* copies, two of them disagreeing). Two Compose files carry the default — the development stack's
* server and the compose lanes' smoke client, because a YAML anchor does not cross files — and the
* build declares both as this task's input.
*/
class ComposeMinioImageMatchesEvidenceTest {
static final String COMPOSE_FILE_PROPERTY = "objectstorage.compose.file";
static final String COMPOSE_FILES_PROPERTY = "objectstorage.compose.files";
private static final Pattern LOCAL_MINIO_DEFAULT =
Pattern.compile(
"x-local-minio-image:\\s*&local-minio-image\\s*\"\\$\\{LOCAL_MINIO_IMAGE:-([^}]+)}\"");
@@ -27,14 +31,21 @@ class ComposeMinioImageMatchesEvidenceTest {
@DisplayName("compose의 기본 MinIO 이미지는 evidence가 측정한 이미지와 같은 digest다")
void theComposeDefaultMinioImageIsTheMeasuredEvidenceImage() throws IOException {
// given
String compose = Files.readString(Path.of(System.getProperty(COMPOSE_FILE_PROPERTY)));
Matcher defaultImage = LOCAL_MINIO_DEFAULT.matcher(compose);
List<Path> composeFiles =
Pattern.compile(Pattern.quote(File.pathSeparator))
.splitAsStream(System.getProperty(COMPOSE_FILES_PROPERTY))
.map(Path::of)
.toList();
// when
String measured = MinioQualificationImage.load(Optional.empty()).minio();
// then
assertThat(defaultImage.find()).as("x-local-minio-image default in the compose file").isTrue();
assertThat(defaultImage.group(1)).isEqualTo(measured);
assertThat(composeFiles).hasSize(2);
for (Path composeFile : composeFiles) {
Matcher defaultImage = LOCAL_MINIO_DEFAULT.matcher(Files.readString(composeFile));
assertThat(defaultImage.find()).as("x-local-minio-image default in %s", composeFile).isTrue();
assertThat(defaultImage.group(1)).as("%s", composeFile).isEqualTo(measured);
}
}
}
@@ -165,7 +165,7 @@ public record RedisTopologyEndpoint(
*
* <p>Deliberately credential-free, and that is not an oversight. A sentinel is a different
* process with its own ACL: it does not load the data nodes' {@code aclfile}, so the accounts in
* {@code infra/redis-sdk/acl} do not exist there and presenting one gets {@code WRONGPASS}. The
* {@code compose/redis/acl} do not exist there and presenting one gets {@code WRONGPASS}. The
* {@code sentinel auth-user} / {@code auth-pass} directives in the lane are about how the
* sentinel authenticates <em>to the monitored primary</em>, which is a different direction
* entirely. Securing the sentinels themselves would mean giving them their own ACL file, and the
+2 -2
View File
@@ -47,7 +47,7 @@ service contributes them to the runtime as beans, one per lane it uses, through
— and builds `LettuceRedisCommandGateway.over(lease.driver())` over a borrowed lease. The last bean
matters only with an admin account: under `prod`, `SecretSourceValidator` refuses a secret that holds
a lane fixture password (`fixture-admin` is in `infra/redis-sdk/acl`), but it learns which variables
a lane fixture password (`fixture-admin` is in `compose/redis/acl`), but it learns which variables
are secrets from the registry, from `secret://` references in the environment and from
`RequiredProductionSecrets` beans — not from a reference held in code. Without the bean the admin
account could run in production on the public lane password (review 2026-11-04 RR3-04-03). The SDK
@@ -107,5 +107,5 @@ The SDK reads none itself. It runs on `redis-runtime`, whose rows in
Contract tests run the operations against this leaf's own in-memory gateway
(`InMemoryRedisCommandGateway`, test sources); the topology endpoint helper comes from
`testFixtures(project(':adapter:outbound:redis-runtime'))`. The real-server lane is
`redisTopologyTest` (see `infra/redis-sdk/README.md`); this leaf declares `standalone`, `sentinel`
`redisTopologyTest` (see [compose/README.md](compose/README.md)); this leaf declares `standalone`, `sentinel`
and `cluster` in `build.gradle`. `tls` is qualified by `redis-runtime`.
@@ -25,9 +25,9 @@ in the repository is a private key in the repository, however the file is named
day, so a stale lane fails visibly instead of drifting.
```bash
REDIS_VERSION=7.4 docker compose -f infra/redis-sdk/tls/compose.yml up -d --wait
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/tls/compose.yml up -d --wait
# The client needs the generated CA; copy it out of the volume first.
docker compose -f infra/redis-sdk/tls/compose.yml cp redis:/tls/ca.crt /tmp/redis-lane-ca.pem
docker compose -f src/adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt /tmp/redis-lane-ca.pem
cd src && ./gradlew :adapter:outbound:redis-runtime:redisTopologyTest \
-Predis.topology.host=127.0.0.1 -Predis.topology.port=6390 \
-Predis.topology.mode=tls -Predis.topology.trust-material=/tmp/redis-lane-ca.pem
@@ -73,12 +73,12 @@ rest of the topology is discovered.
```bash
# Standalone
REDIS_VERSION=7.4 docker compose -f infra/redis-sdk/standalone/compose.yml up -d --wait
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/standalone/compose.yml up -d --wait
cd src && ./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:outbound:redis-sdk:redisTopologyTest :adapter:outbound:cache-redis:redisTopologyTest \
-Predis.topology.host=localhost -Predis.topology.port=6379 -Predis.topology.mode=standalone
# Sentinel — the port is a sentinel, and the monitored primary has to be named
REDIS_VERSION=7.4 docker compose -f infra/redis-sdk/sentinel/compose.yml up -d --wait
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/sentinel/compose.yml up -d --wait
cd src && ./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:outbound:redis-sdk:redisTopologyTest \
-Predis.topology.host=localhost -Predis.topology.port=27010 \
-Predis.topology.mode=sentinel -Predis.topology.master=skeleton
@@ -86,7 +86,7 @@ cd src && ./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:o
# Cluster — `up --wait` waits for the `ready` gate, not just for six servers that answer PING.
# Slot assignment finishes after the nodes are healthy, and a client that connects in between sees
# CLUSTERDOWN for reasons that have nothing to do with the SDK.
REDIS_VERSION=7.4 docker compose -f infra/redis-sdk/cluster/compose.yml up -d --wait
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/cluster/compose.yml up -d --wait
cd src && ./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:outbound:redis-sdk:redisTopologyTest :adapter:outbound:cache-redis:redisTopologyTest \
-Predis.topology.host=localhost -Predis.topology.port=7100 -Predis.topology.mode=cluster
```
@@ -102,7 +102,7 @@ declare fails instead of running nothing, so run only the leaves listed for the
| cluster | `LiveRedisCompositionTest` | `LiveRedisClusterTest`, `LiveRedisClusterTransactionTest` | `LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest` |
| tls | `LiveRedisTlsTest` | — | — |
Tear a lane down with `docker compose -f infra/redis-sdk/<lane>/compose.yml down -v`.
Tear a lane down with `docker compose -f src/adapter/outbound/redis-sdk/compose/<lane>/compose.yml down -v`.
| Lane | Ports | Notes |
| --- | --- | --- |
@@ -25,7 +25,7 @@ x-node: &node
image: "redis:${REDIS_VERSION:-7.4}"
network_mode: host
volumes:
- ../acl:/etc/redis/acl:ro
- ../../../../../../compose/redis/acl:/etc/redis/acl:ro
entrypoint:
- /bin/sh
- -c
@@ -29,7 +29,7 @@ x-data-node: &data-node
image: "redis:${REDIS_VERSION:-7.4}"
network_mode: host
volumes:
- ../acl:/etc/redis/acl:ro
- ../../../../../../compose/redis/acl:/etc/redis/acl:ro
entrypoint:
- /bin/sh
- -c
@@ -16,7 +16,7 @@ services:
- --aclfile
- /etc/redis/acl/lane-fixture-accounts.acl
volumes:
- ../acl:/etc/redis/acl:ro
- ../../../../../../compose/redis/acl:/etc/redis/acl:ro
ports:
- "${REDIS_PORT:-6379}:6379"
healthcheck:
@@ -38,7 +38,7 @@ services:
certs:
condition: service_completed_successfully
volumes:
- ../acl:/etc/redis/acl:ro
- ../../../../../../compose/redis/acl:/etc/redis/acl:ro
- tls:/tls:ro
command:
- redis-server
@@ -29,11 +29,11 @@ import org.junit.jupiter.api.Test;
* so selecting it without an endpoint is an error rather than a skip.
*
* <p>What lives here is what the in-memory gateway is honest about not proving. The ACL assertions
* below are the first of those: the accounts in {@code infra/redis-sdk/acl} are the last
* enforcement boundary, and whether they actually grant what the command policy catalog says each
* access level may issue is a question only the server answers. Writing this test already found one
* defect — the advanced account granted {@code SMEMBERS} and {@code SORT}, which are {@code
* RAW_ONLY} and belong to the raw gateway account alone.
* below are the first of those: the accounts in {@code compose/redis/acl} are the last enforcement
* boundary, and whether they actually grant what the command policy catalog says each access level
* may issue is a question only the server answers. Writing this test already found one defect — the
* advanced account granted {@code SMEMBERS} and {@code SORT}, which are {@code RAW_ONLY} and belong
* to the raw gateway account alone.
*/
@Tag("redis-topology")
@Tag("lane-standalone")
+1 -1
View File
@@ -130,7 +130,7 @@ README의 "startup" 절에 있다.
- **prod 에서 깨지면 부팅 자체를 거부하는 fail-fast 가드다.** 두 가지 prod 불변식을 context refresh
완료 전에 강제한다. (1) `__LOCAL_DEV_` 접두사를 가진 dev/local 가짜 자격증명 값이 prod 프로파일에
도달하는 것은 잘못 로드된 사고이므로 부팅을 중단시킨다. 비밀값이 `fixture-`로 시작해도 같다. 이 저장소가
lane용으로 적어 둔 공개 비밀번호(`infra/redis-sdk/acl`의 Redis ACL fixture, compose lane의
lane용으로 적어 둔 공개 비밀번호(`compose/redis/acl`의 Redis ACL fixture, compose lane의
`REDIS_LANE_*`)라서, lane 환경이나 lane ACL 파일을 베낀 배포가 그대로 운영에 뜨는 것을 막는다
(review 2026-11-03 RR-07-04). 이 검사는 비밀값만 본다 — 레지스트리의 `secret` 행
(`CLASSIFIED_SECRETS`), 모듈이 기여한 비밀, 환경 값에 든 `secret://…/<VAR>` 참조가 가리키는 변수
+5 -3
View File
@@ -341,12 +341,14 @@ def repositoryRootForContractTests = rootProject.projectDir.parentFile
def repositoryContractExcludes = ['**/build/**', '**/.gradle/**', '**/node_modules/**']
def repositoryContractInputs = files(
fileTree(repositoryRootForContractTests) {
include '.github/**', 'infra/**', 'scripts/**', '*.yml', '*.example', '.tool-versions'
include '.github/**', 'compose/**', 'scripts/**', '*.yml', '*.yaml', '*.example', '.tool-versions'
exclude '**/*.md'
exclude repositoryContractExcludes
},
fileTree(rootProject.projectDir) {
include 'config/**', '**/*.gradle', 'gradle/*.toml', 'Dockerfile*', '.env*', '**/src/main/**'
// The compose lane fixtures this leaf owns (the lane contract, overlays, smoke clients).
include 'app-bootstrap/compose-lanes/**'
exclude '**/*.md'
exclude repositoryContractExcludes
})
@@ -405,7 +407,7 @@ tasks.named('conditionalTransportBuildContractTest', Test) {
}
tasks.named('integrationTest', Test) {
inputs.files(fileTree(repositoryRootForContractTests) {
include '*.yml', 'infra/**'
include 'compose.yaml', 'compose/**', 'scripts/*compose*.sh', 'src/app-bootstrap/compose-lanes/**'
exclude repositoryContractExcludes
}).withPathSensitivity(PathSensitivity.RELATIVE).withPropertyName('composeFiles')
}
@@ -475,7 +477,7 @@ def compositionRuntimeClasspath = { String name ->
}
// The qualification artifact: this composition with every capability on the classpath. It is what
// the Compose lanes (config/runtime/compose-profile-contracts.json) boot, because a lane that turns
// the Compose lanes (compose-lanes/compose-profile-contracts.json) boot, because a lane that turns
// JPA or Kafka on needs the module in the image, and `bootJar` — the default composition a service
// ships — carries none of them. It is never released: `release.yml` builds `stageDockerJar`.
// Each capability is on while present, so a lane switches off what it is not about.
@@ -1,14 +1,13 @@
{
"$comment": "The lane SSOT. Each row fixes a Compose profile, a file stack, an explicit Spring runtime and the exact set of services that stack must render — exact, not a superset, because a lane that quietly gains a service is a lane whose evidence describes something else. A Compose profile selects services and never implies a Spring profile; the wrapper injects the runtime named here.",
"$comment": "The lane SSOT. Each row fixes the Compose profiles it enables, a file stack, an explicit Spring runtime and the exact set of services that stack must render — exact, not a superset, because a lane that quietly gains a service is a lane whose evidence describes something else. A Compose profile selects services and never implies a Spring profile; the wrapper injects the runtime named here. The base file is the development stack (compose.yaml), whose backing services carry capability profiles (jpa, redis, kafka, mongo, objectstorage, auth, mail); the lane-only services in lane-services.yaml carry their own (schema-streams, smoke-*).",
"minimumComposeVersion": "2.24.4",
"composeFiles": {
"base": "docker-compose.yml",
"infra": "docker-compose.infra.yml",
"local": "docker-compose.local.yml",
"dev": "docker-compose.dev.yml",
"prod-smoke": "docker-compose.prod-smoke.yml",
"tls": "docker-compose.tls.yml",
"fileserver": "infra/fileserver/compose/docker-compose.fileserver.yml"
"base": "compose.yaml",
"lane": "src/app-bootstrap/compose-lanes/lane-services.yaml",
"dev": "src/app-bootstrap/compose-lanes/dev.yaml",
"prod-smoke": "src/app-bootstrap/compose-lanes/prod-smoke.yaml",
"tls": "src/app-bootstrap/compose-lanes/tls.yaml",
"fileserver": "src/app-bootstrap/compose-lanes/fileserver.yaml"
},
"$serviceRoles": "Every service a lane renders plays exactly one of three roles, and the wrapper treats them differently: longRunningServices are the only `up --wait` targets, preStartServices run with `run --rm` before the application starts because it depends on what they do, and oneShotServices run with `run --rm` after it is healthy because they exercise it. The two catalogues below name every service that is not a --wait target anywhere; a one-shot passed to `up --wait` waits forever for a container built to exit.",
"preStartServices": [
@@ -27,10 +26,9 @@
"lanes": [
{
"id": "off-local",
"composeProfile": null,
"composeProfiles": [],
"files": [
"base",
"local"
"base"
],
"springRuntime": "local",
"services": [
@@ -47,7 +45,7 @@
},
{
"id": "off-dev",
"composeProfile": null,
"composeProfiles": [],
"files": [
"base",
"dev"
@@ -67,7 +65,7 @@
},
{
"id": "off-prod",
"composeProfile": null,
"composeProfiles": [],
"files": [
"base",
"prod-smoke"
@@ -87,11 +85,11 @@
},
{
"id": "local-jpa",
"composeProfile": "local-jpa",
"composeProfiles": [
"jpa"
],
"files": [
"base",
"infra",
"local"
"base"
],
"springRuntime": "local",
"services": [
@@ -118,11 +116,11 @@
},
{
"id": "local-mongo",
"composeProfile": "local-mongo",
"composeProfiles": [
"mongo"
],
"files": [
"base",
"infra",
"local"
"base"
],
"springRuntime": "local",
"services": [
@@ -151,11 +149,11 @@
},
{
"id": "local-messaging",
"composeProfile": "local-messaging",
"composeProfiles": [
"kafka"
],
"files": [
"base",
"infra",
"local"
"base"
],
"springRuntime": "local",
"services": [
@@ -181,11 +179,12 @@
},
{
"id": "local-messaging-outbox",
"composeProfile": "local-messaging-outbox",
"composeProfiles": [
"jpa",
"kafka"
],
"files": [
"base",
"infra",
"local"
"base"
],
"springRuntime": "local",
"services": [
@@ -221,11 +220,15 @@
},
{
"id": "local-notification-ingest",
"composeProfile": "local-notification-ingest",
"composeProfiles": [
"jpa",
"auth",
"schema-streams",
"smoke-notification"
],
"files": [
"base",
"infra",
"local"
"lane"
],
"springRuntime": "local",
"services": [
@@ -270,11 +273,16 @@
},
{
"id": "local-notification-serving",
"composeProfile": "local-notification-serving",
"composeProfiles": [
"jpa",
"auth",
"mail",
"schema-streams",
"smoke-notification"
],
"files": [
"base",
"infra",
"local"
"lane"
],
"springRuntime": "local",
"services": [
@@ -331,11 +339,16 @@
},
{
"id": "local-notification-handoff",
"composeProfile": "local-notification-handoff",
"composeProfiles": [
"jpa",
"auth",
"mail",
"schema-streams",
"smoke-notification"
],
"files": [
"base",
"infra",
"local"
"lane"
],
"springRuntime": "local",
"services": [
@@ -400,11 +413,14 @@
},
{
"id": "local-graphql",
"composeProfile": "local-graphql",
"composeProfiles": [
"auth",
"smoke-auth",
"smoke-graphql"
],
"files": [
"base",
"infra",
"local"
"lane"
],
"springRuntime": "local",
"services": [
@@ -433,11 +449,11 @@
},
{
"id": "local-redis",
"composeProfile": "local-redis",
"composeProfiles": [
"redis"
],
"files": [
"base",
"infra",
"local"
"base"
],
"springRuntime": "local",
"services": [
@@ -467,11 +483,13 @@
{
"id": "local-fileserver",
"$comment": "The Fileserver keeps its metadata in PostgreSQL through JPA (FileserverJpaPersistenceConfig needs the entityManagerFactory), so the lane without a database could never start: the application refused at startup and the lane reported an unhealthy container. PostgreSQL, the JPA module, and the fileserver schema stream installed and promoted before the application starts, the way the notification lanes get theirs.",
"composeProfile": "local-fileserver",
"composeProfiles": [
"jpa",
"schema-streams"
],
"files": [
"base",
"infra",
"local",
"lane",
"fileserver"
],
"springRuntime": "local",
@@ -515,10 +533,9 @@
},
{
"id": "local-httpclient",
"composeProfile": "local-httpclient",
"composeProfiles": [],
"files": [
"base",
"local"
"base"
],
"springRuntime": "local",
"services": [
@@ -546,11 +563,16 @@
},
{
"id": "shared-infra-local",
"composeProfile": "shared-infra",
"composeProfiles": [
"jpa",
"auth",
"objectstorage",
"smoke-auth",
"smoke-objectstorage"
],
"files": [
"base",
"infra",
"local"
"lane"
],
"springRuntime": "local",
"services": [
@@ -588,10 +610,16 @@
},
{
"id": "shared-infra-dev",
"composeProfile": "shared-infra",
"composeProfiles": [
"jpa",
"auth",
"objectstorage",
"smoke-auth",
"smoke-objectstorage"
],
"files": [
"base",
"infra",
"lane",
"dev"
],
"springRuntime": "dev",
@@ -630,10 +658,16 @@
},
{
"id": "prod-smoke",
"composeProfile": "prod-smoke",
"composeProfiles": [
"jpa",
"auth",
"objectstorage",
"smoke-auth",
"smoke-objectstorage"
],
"files": [
"base",
"infra",
"lane",
"prod-smoke",
"tls"
],
@@ -673,14 +707,26 @@
},
{
"id": "all-adapters",
"composeProfile": "all-adapters",
"composeProfiles": [
"jpa",
"mongo",
"kafka",
"redis",
"auth",
"mail",
"schema-streams",
"smoke-auth",
"smoke-graphql",
"smoke-notification"
],
"files": [
"base",
"infra",
"local",
"lane",
"fileserver"
],
"springRuntime": "local",
"$memoryComment": "Every capability on at once does not fit the 512m the development stack gives the application: the JVM sized its heap to 75% of the limit and the rest (metaspace for every module, code cache, threads) took the container past it, so the kernel killed it and restart: unless-stopped hid the kill whenever it missed the smoke requests (integration-r9, 2026-11-07). The lane raises the limit for itself; the wrapper writes it into the generated overlay and fails a lane whose containers restarted.",
"appMemoryLimit": "1g",
"services": [
"app",
"auth-smoke",
@@ -795,6 +841,6 @@
"redis"
],
"$vendorComment": "expectedPersistenceVendor is the vendor the application must report, not the one the lane started: info.capabilities.persistence-jpa.vendor while JPA is on, none while it is off. A reported postgresql is the database the queries go to, because the JPA module refuses to start when the selected vendor is postgresql and the datasource it reaches is not PostgreSQL (JpaDataSourceProfileValidator). local-jpa passed for a while against H2 while a PostgreSQL container it never touched sat beside it, because application-local.yml pins an in-memory URL that outranks the lane's environment.",
"$redisComment": "The lanes that switch Redis on authenticate the way a deployment does. Their Redis loads infra/redis-sdk/acl/lane-fixture-accounts.acl, which turns the passwordless default user off, and the application connects as the two named accounts that file provisions: ca-skeleton-application for ordinary commands and ca-skeleton-application-advanced for registered scripts. Both references use the secret://<account>@environment/<variable> form; without the account part the client authenticates as the disabled default user. The two REDIS_LANE_* values are that file's fixture passwords (infra/redis-sdk/acl/README.md), not deployment credentials, and deliberately carry no APP_ prefix: they are not application settings, only what these references point at. APP_REDIS_NAMESPACE_ENVIRONMENT is prod because the fixture accounts are fenced to ~prod:*, the namespace every other test against that file uses; under the default local namespace the first key a capability wrote would be refused with NOPERM after startup had reported healthy. Before this the lanes declared anonymous-access-accepted against an open Redis, and the two startup warnings that trade prints (no credential, no advanced account) failed their startup-is-silent check — which is right, because in production both are risks. scripts/verify-compose-profile-contracts.sh check 7 holds a Redis lane's references, passwords and namespace to the account lines of the file its Redis actually mounts.",
"$redisComment": "The lanes that switch Redis on authenticate the way a deployment does. Their Redis loads compose/redis/acl/lane-fixture-accounts.acl, which turns the passwordless default user off, and the application connects as the two named accounts that file provisions: ca-skeleton-application for ordinary commands and ca-skeleton-application-advanced for registered scripts. Both references use the secret://<account>@environment/<variable> form; without the account part the client authenticates as the disabled default user. The two REDIS_LANE_* values are that file's fixture passwords (compose/redis/acl/README.md), not deployment credentials, and deliberately carry no APP_ prefix: they are not application settings, only what these references point at. APP_REDIS_NAMESPACE_ENVIRONMENT is prod because the fixture accounts are fenced to ~prod:*, the namespace every other test against that file uses; under the default local namespace the first key a capability wrote would be refused with NOPERM after startup had reported healthy. Before this the lanes declared anonymous-access-accepted against an open Redis, and the two startup warnings that trade prints (no credential, no advanced account) failed their startup-is-silent check — which is right, because in production both are risks. scripts/verify-compose-profile-contracts.sh check 7 holds a Redis lane's references, passwords and namespace to the account lines of the file its Redis actually mounts.",
"$flywayComment": "SPRING_FLYWAY_LOCATIONS is deliberately absent. Seven lanes listed every capability stream there, and it could never have worked: the db/migration/jpa/* streams each declare a V1, so one Flyway instance over all of them fails with 'Found more than one migration with version 1'. Each stream is its own stream with its own history table by design. The setting was inert until Wave 2 stopped PostgreSqlPersistenceConfig from overriding spring.flyway.locations, and the lanes passed while their own configuration was being discarded. Applying a capability stream needs a Flyway execution per stream — the operator sequence PostgreSqlNotificationPersistenceUnitIntegrationTest and FileserverRoundTripContractTest both perform in their fixtures — and that is what the notification lanes still need."
}
@@ -1,8 +1,11 @@
# =============================================================================
# feature-container-runtime-contract — dev environment override
#
# Merge with base:
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up
# 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
@@ -35,7 +38,7 @@ services:
# 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 the local and prod-smoke overlays own theirs. It was
# 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
@@ -86,7 +89,7 @@ services:
target: /var/tmp/heap
bind:
create_host_path: true
# The same network the shared infrastructure lives on. The local overlay joins it and the dev
# 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
@@ -96,6 +99,6 @@ services:
- caskeleton-infra
networks:
# Defined in docker-compose.infra.yml, where the services that share it live.
# Defined in compose.yaml, where the services that share it live.
caskeleton-infra:
external: false
@@ -3,14 +3,13 @@
#
# Usage, on top of a stack whose image carries the fileserver module (a service that selected
# `:composition:fileserver-platform`, or COMPOSITION=qualification):
# docker compose -f docker-compose.yml -f docker-compose.local.yml \
# -f infra/fileserver/compose/docker-compose.fileserver.yml up
# docker compose -f compose.yaml -f src/app-bootstrap/compose-lanes/fileserver.yaml up
#
# Why a file of its own (review 2026-11-01 07-08, capability criterion 7): the default image and
# docker-compose.yml carry no fileserver, so they no longer carry its volume either. Before, every
# compose.yaml carry no fileserver, so they no longer carry its volume either. Before, every
# container — default composition included — mounted a volume for a module it did not have, and the
# image declared it a VOLUME. It sits with the rest of the capability's infrastructure
# (infra/fileserver), so removing the capability removes it with that directory.
# image declared it a VOLUME. It is a compose lane fixture (the lanes local-fileserver and
# all-adapters add it); a service that selects the capability adds the same volume to its own stack.
#
# The volume is a named volume, not a tmpfs and not the read-only root: published content must
# outlive the container that wrote it. Back it with real storage in any deployment that keeps files.
@@ -0,0 +1,245 @@
# =============================================================================
# compose lane 전용 서비스 — 개발 환경(저장소 루트 compose.yaml)에는 없다.
#
# 스키마 적용 one-shot 둘과 smoke client 넷이다. 모두 profile이 있어서 lane이 그 profile을 댈 때만 뜬다.
# 어느 lane이 무엇을 쓰는지는 compose-profile-contracts.json이 정한다. 이 파일은 compose.yaml 뒤에
# -f로 합쳐지므로 경로는 저장소 루트 기준이다.
#
# profile 서비스
# schema-streams db-migrate-capabilities, db-promote-capabilities
# smoke-auth auth-smoke
# smoke-graphql graphql-smoke
# smoke-objectstorage object-storage-smoke
# smoke-notification notification-smoke
# =============================================================================
# The object storage smoke client runs the MinIO server image (see below). YAML anchors do not cross
# files, so this is a second copy of compose.yaml's default; ComposeMinioImageMatchesEvidenceTest
# holds both to the measured evidence digest.
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
services:
# ---- Capability schema streams ------------------------------------------------
# Two pre-start one-shots, in this order, because a capability stream is an operator sequence
# rather than a property.
#
# Install: each stream under db/migration/jpa keeps its own Flyway history table — they all declare
# a V1, so one Flyway pointed at all of them fails outright — and each registers itself
# INSTALLED_INACTIVE.
#
# Promote: an operator sanctions the installed schema, and the application refuses to start until
# that has happened. That is the fail-closed half of the same design, so it cannot be folded into
# the install step without making "the tables exist" and "this is sanctioned" the same event.
#
# They are also two images because they must be: flyway/flyway ships no psql, so the promotion
# could not have run in the migration container at all.
#
# Both run before `up`, not with the smoke clients after it — the application is what they are a
# precondition for. The lane contract's preStartServices carries that ordering.
db-migrate-capabilities:
profiles:
- schema-streams
image: flyway/flyway:11.1.0
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/apply-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./src/app-bootstrap/compose-lanes/postgres/apply-capability-streams.sh
target: /opt/capability-streams/apply-capability-streams.sh
read_only: true
- type: bind
source: ./src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
target: /flyway/sql
read_only: true
- type: bind
source: ./src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform
target: /flyway/streams/notification-platform
read_only: true
- type: bind
source: ./src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver
target: /flyway/streams/fileserver
read_only: true
networks:
- caskeleton-infra
restart: "no"
db-promote-capabilities:
profiles:
- schema-streams
image: postgres:16-alpine
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/promote-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./src/app-bootstrap/compose-lanes/postgres/promote-capability-streams.sh
target: /opt/capability-streams/promote-capability-streams.sh
read_only: true
networks:
- caskeleton-infra
restart: "no"
# ---- One-shot smoke clients --------------------------------------------------
# Never `up --wait` targets. Each is run with `run --rm` and must exit zero; a missing, skipped or
# non-zero one fails its lane rather than being treated as "not applicable".
graphql-smoke:
profiles:
- smoke-graphql
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the mounted 0600 client secret, same as auth-smoke.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/smoke/graphql-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
# Spring for GraphQL serves its own endpoint through a router function rather than an
# annotated controller, so the presentation base-path prefix does not apply to it.
GRAPHQL_PATH: "${GRAPHQL_PATH:-/graphql}"
volumes:
- type: bind
source: ./src/app-bootstrap/compose-lanes/smoke
target: /opt/smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
auth-smoke:
profiles:
- smoke-auth
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# The client secret is written on the host at mode 0600 by the qualification wrapper and mounted
# in. The Keycloak image happens to run as the same uid the wrapper writes as; this image runs as
# uid 100, so it read "Permission denied" and the lane failed on the smoke client rather than on
# anything it was checking. Compose ignores the secret's uid/gid/mode options outside swarm, so
# the container reads it as root instead. The two alternatives are both worse: loosening the host
# file to world-readable leaves a credential readable by every process on the machine, and passing
# the value as an environment variable puts it in `docker compose config` output and in ps.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/smoke/auth-smoke.sh"]
environment:
# The same issuer URL the application is given. A token obtained from one URL and validated
# against another proves nothing, and localhost means a different host inside each container.
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
APP_BASE_URL: "http://app:8080"
# Supplied per runtime, because the same endpoint has two addresses: application-local.yml
# pins presentation.api-base-path to /api and the shipped default is /v1. The qualification
# wrapper exports the value that matches the lane's Spring runtime.
APP_HEALTH_PATH: "${APP_HEALTH_PATH:-/v1/healthcheck}"
volumes:
- type: bind
source: ./src/app-bootstrap/compose-lanes/smoke
target: /opt/smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
# The server image, not the mc client image: the mc image ships no sed, grep or cmp, and the round-trip
# client needs a digest tool. See smoke/object-storage-smoke.sh for how that went unnoticed. The
# lane already pulls this image for the server itself.
object-storage-smoke:
profiles:
- smoke-objectstorage
image: *local-minio-image
depends_on:
minio-init:
condition: service_completed_successfully
entrypoint: ["/bin/sh", "/opt/smoke/object-storage-smoke.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./src/app-bootstrap/compose-lanes/smoke
target: /opt/smoke
read_only: true
networks:
- caskeleton-infra
restart: "no"
notification-smoke:
profiles:
- smoke-notification
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the same reason auth-smoke uses it: the mounted client secret is mode 0600 on the
# host and this image otherwise runs as uid 100, which reads "Permission denied". The lane then
# fails on the smoke client rather than on anything it was checking.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/smoke/notification-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
MAILPIT_BASE_URL: "http://mailpit:8025"
# ingest | serving | handoff-verify — which phase of the lane this invocation is.
#
# No default, deliberately. It defaulted to `ingest`, and local-notification-serving therefore
# ran the ingest assertions — "accepted, and nothing was delivered" — against an application in
# SERVING mode. The lane passed while testing the opposite of what it is named for, and would
# have kept passing for as long as the check happened to run before the dispatch worker. An
# unset value now renders empty and the client refuses it.
# `:-` and not a value: an explicit empty default keeps Compose from warning about an unset
# variable on every lane that never runs this client, while still rendering empty so the
# client refuses it.
NOTIFICATION_SMOKE_PHASE: "${NOTIFICATION_SMOKE_PHASE:-}"
APP_BASE_PATH: "${APP_BASE_PATH:-/api}"
# Submission and template publication are authenticated like every other non-public path, so
# this client obtains a token the same way auth-smoke does — client credentials against the
# same issuer URL the application validates against.
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
volumes:
- type: bind
source: ./src/app-bootstrap/compose-lanes/smoke
target: /opt/smoke
read_only: true
# The handoff lane runs this client twice in one project and the second run needs the request
# id the first accepted, so the state lives in a named volume that outlives a `run --rm`
# container and is removed with the project by the teardown's --volumes.
#
# Its own path, not a subdirectory of the script mount above: a volume nested inside a
# read-only bind cannot be created, because the runtime has to mkdir the mountpoint in a
# filesystem it was just told is read-only.
- type: volume
source: caskeleton-notification-smoke-state
target: /opt/notification-smoke-state
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
volumes:
caskeleton-notification-smoke-state:
driver: local
@@ -22,7 +22,7 @@
#
# Each stream registers itself INSTALLED_INACTIVE. Nothing here promotes anything — a table existing
# is not the same as a capability being sanctioned to use it, and this image has no psql to blur the
# two with even if that were wanted. infra/postgres/promote-capability-streams.sh is the operator
# two with even if that were wanted. promote-capability-streams.sh is the operator
# half, and NotificationSchemaActivation refusing startup until it has run is the fail-closed third.
#
# CAPABILITY_STREAMS is a space-separated list of stream names (the directory names under
@@ -8,7 +8,7 @@
#
# So the lane brings a real certificate instead. The qualification wrapper generates a CA and a
# server certificate for the host name `db` per run, at mode 0600, and removes both on teardown; the
# realm-secret pattern, applied to a keypair. Nothing here is committed: infra/postgres/tls holds
# realm-secret pattern, applied to a keypair. Nothing here is committed: compose-lanes/postgres/tls holds
# only a .gitignore.
#
# `verify-full` is deliberate rather than `verify-ca`. `verify-ca` proves the certificate was issued
@@ -19,7 +19,7 @@
services:
db:
# Runs as root just long enough to install the key where postgres can read it, then hands over
# to the official entrypoint. See infra/postgres/entrypoint.sh for why a bind mount cannot do it.
# to the official entrypoint. See compose-lanes/postgres/entrypoint.sh for why a bind mount cannot do it.
entrypoint: ["/bin/sh", "/opt/postgres-entrypoint/entrypoint.sh"]
command:
- "postgres"
@@ -31,11 +31,11 @@ services:
- "ssl_key_file=/etc/postgresql-tls/server.key"
volumes:
- type: bind
source: ./infra/postgres/entrypoint.sh
source: ./src/app-bootstrap/compose-lanes/postgres/entrypoint.sh
target: /opt/postgres-entrypoint/entrypoint.sh
read_only: true
- type: bind
source: ./infra/postgres/tls
source: ./src/app-bootstrap/compose-lanes/postgres/tls
target: /opt/postgres-tls
read_only: true
@@ -47,4 +47,4 @@ services:
secrets:
postgres-ca:
file: ./infra/postgres/tls/ca.crt
file: ./src/app-bootstrap/compose-lanes/postgres/tls/ca.crt
@@ -27,21 +27,15 @@ class ComposeMergeCharacterizationTest {
private static final Path REPOSITORY_ROOT = repositoryRoot();
@Test
@DisplayName("the base stack renders")
void baseStackRenders() {
assertStackRenders("docker-compose.yml");
@DisplayName("the development stack renders")
void developmentStackRenders() {
assertStackRenders("compose.yaml");
}
@Test
@DisplayName("the local stack renders")
void localStackRenders() {
assertStackRenders("docker-compose.yml", "docker-compose.local.yml");
}
@Test
@DisplayName("the dev stack renders")
@DisplayName("the dev lane stack renders")
void devStackRenders() {
assertStackRenders("docker-compose.yml", "docker-compose.dev.yml");
assertStackRenders("compose.yaml", "src/app-bootstrap/compose-lanes/dev.yaml");
}
/**
@@ -112,7 +106,7 @@ class ComposeMergeCharacterizationTest {
private static Path repositoryRoot() {
Path candidate = Path.of("").toAbsolutePath();
while (candidate != null && !Files.isRegularFile(candidate.resolve("docker-compose.yml"))) {
while (candidate != null && !Files.isRegularFile(candidate.resolve("compose.yaml"))) {
candidate = candidate.getParent();
}
if (candidate == null) {
@@ -27,8 +27,8 @@ public class AsyncExecutorConfig {
* How long close waits for queued async work. It is spent after the web server's graceful drain
* ({@code spring.lifecycle.timeout-per-shutdown-phase}, 30s) has finished, because Spring stops
* lifecycle beans before it destroys this executor — so the two add up. The container grace in
* the root {@code docker-compose.yml} is sized to that sum; {@code
* DeveloperExperienceContractTest} fails when it is not (07-07).
* the root {@code compose.yaml} is sized to that sum; {@code DeveloperExperienceContractTest}
* fails when it is not (07-07).
*/
public static final int AWAIT_TERMINATION_SECONDS = 19;
@@ -36,13 +36,13 @@ public final class SecretSourceValidator implements StartupRule {
/**
* Prefix of the passwords this repository writes down for its lanes: the Redis ACL fixtures in
* {@code infra/redis-sdk/acl} and the Compose lanes' {@code REDIS_LANE_*} values that connect
* with them. They are public — anyone who can read the repository has them — so under {@code
* prod} a secret holding one is refused (review 2026-11-03 RR-07-04). A deployment that copied a
* lane's environment — which is also what an application needs to authenticate against a Redis
* that loaded the lane ACL file — would start with credentials it does not own. It cannot see a
* Redis server that loaded that file while the application uses real passwords; the ACL README
* says why no deployment loads it.
* {@code compose/redis/acl} and the Compose lanes' {@code REDIS_LANE_*} values that connect with
* them. They are public — anyone who can read the repository has them — so under {@code prod} a
* secret holding one is refused (review 2026-11-03 RR-07-04). A deployment that copied a lane's
* environment — which is also what an application needs to authenticate against a Redis that
* loaded the lane ACL file — would start with credentials it does not own. It cannot see a Redis
* server that loaded that file while the application uses real passwords; the ACL README says why
* no deployment loads it.
*
* <p>Only secrets are read for it (review 2026-11-04 RR2-04-01, owner decision): {@code fixture-}
* is an ordinary word before it is this repository's password prefix, and a pod named after a
@@ -202,7 +202,7 @@ public final class SecretSourceValidator implements StartupRule {
+ secret
+ " holds a lane fixture password ('"
+ REPOSITORY_FIXTURE_PREFIX
+ "…', public in infra/redis-sdk/acl)"));
+ "…', public in compose/redis/acl)"));
}
}
@@ -92,7 +92,7 @@ management:
enabled: true
# The `info.*` tree only, not the environment: each capability module ships an
# info.capabilities.<name> entry beside its switch, and the Compose smoke lanes read it to check
# which capabilities the application actually turned on (compose-profile-contracts.json).
# which capabilities the application actually turned on (compose-lanes/compose-profile-contracts.json).
env:
enabled: true
@@ -24,14 +24,13 @@ import org.yaml.snakeyaml.constructor.SafeConstructor;
* criterion 7: the only place that knows a module is the module).
*
* <p>The default image used to create the fileserver storage directory and declare it a {@code
* VOLUME}, and {@code docker-compose.yml} mounted a {@code fileserver-data} volume into every
* container — in a composition that has no fileserver module at all. A reader took the volume as a
* sign the capability was on, and every plain {@code docker run} created an anonymous volume nobody
* wrote to. The volume now lives in {@code infra/fileserver/compose/docker-compose.fileserver.yml},
* beside the rest of the capability's infrastructure, which a lane or a developer adds with the
* capability. Its ownership is set by a one-shot that runs as root in the application's own image,
* so a fresh volume, a reused one and a bind mount all end up owned by the account the application
* runs as.
* VOLUME}, and the root Compose file mounted a {@code fileserver-data} volume into every container
* — in a composition that has no fileserver module at all. A reader took the volume as a sign the
* capability was on, and every plain {@code docker run} created an anonymous volume nobody wrote
* to. The volume now lives in {@code src/app-bootstrap/compose-lanes/fileserver.yaml}, an overlay a
* lane (or a service that selects the capability) adds with the capability. Its ownership is set by
* a one-shot that runs as root in the application's own image, so a fresh volume, a reused one and
* a bind mount all end up owned by the account the application runs as.
*/
@Tag("repository-contract")
class CapabilityStorageOverlayContractTest {
@@ -39,7 +38,9 @@ class CapabilityStorageOverlayContractTest {
private static final Path REPOSITORY_ROOT =
RepositoryContractResources.fromSystemProperty().repositoryRoot();
private static final String OVERLAY = "infra/fileserver/compose/docker-compose.fileserver.yml";
private static final String OVERLAY = "src/app-bootstrap/compose-lanes/fileserver.yaml";
private static final String CONTRACTS =
"src/app-bootstrap/compose-lanes/compose-profile-contracts.json";
private static final String OVERLAY_KEY = "fileserver";
private static final String STORAGE_INIT = "fileserver-storage-init";
private static final String STORAGE_ROOT = "/var/lib/backend/files";
@@ -53,7 +54,7 @@ class CapabilityStorageOverlayContractTest {
@DisplayName("기본 Dockerfile과 기본 compose는 선택 capability 이름을 담지 않는다")
void theDefaultImageAndComposeNameNoOptionalCapability() throws IOException {
// given
List<String> defaultContainerFiles = List.of("src/Dockerfile", "docker-compose.yml");
List<String> defaultContainerFiles = List.of("src/Dockerfile", "compose.yaml");
// when
List<String> mentions = new ArrayList<>();
@@ -116,7 +117,7 @@ class CapabilityStorageOverlayContractTest {
void theFileserverVolumeIsHandedToTheApplicationAccountBeforeTheApplicationStarts()
throws IOException {
// given
Map<?, ?> base = yaml(read("docker-compose.yml"));
Map<?, ?> base = yaml(read("compose.yaml"));
Map<?, ?> overlay = yaml(read(OVERLAY));
// when
@@ -144,7 +145,7 @@ class CapabilityStorageOverlayContractTest {
@DisplayName("fileserver를 켜는 lane만, 그리고 모두 fileserver overlay와 소유권 one-shot을 쓴다")
void exactlyTheLanesThatSwitchTheFileserverOnBringItsOverlay() throws IOException {
// given
Map<?, ?> contracts = yaml(read("src/config/runtime/compose-profile-contracts.json"));
Map<?, ?> contracts = yaml(read(CONTRACTS));
// when
List<String> mismatched = new ArrayList<>();
@@ -72,14 +72,18 @@ class DeveloperExperienceContractTest {
@Test
@Tag("repository-contract")
void localComposeSupportsDatabaseMigrationAndPublicHealthSmoke() throws IOException {
String base = read("docker-compose.yml");
String local = read("docker-compose.local.yml");
String compose = read("compose.yaml");
assertThat(base).contains("RELEASE_VERSION:").contains("GIT_SHA:").contains("SOURCE_URL:");
assertThat(local)
assertThat(compose)
.contains("RELEASE_VERSION:")
.contains("GIT_SHA:")
.contains("SOURCE_URL:")
.contains("env_file:")
.contains("./src/.env")
.doesNotContain("5432:5432")
.contains("http://localhost:9001/actuator/health/readiness");
assertThat(read("scripts/bootstrap-local.sh"))
.contains("compose.yaml")
.contains("http://localhost:8080/api/healthcheck");
}
@@ -88,10 +92,9 @@ class DeveloperExperienceContractTest {
* database the compose stack keeps on its internal network only is unreachable from there, and
* every host-side run dies in the startup migration phase with a connection refusal.
*
* <p>The service moved to docker-compose.infra.yml when infrastructure stopped being spread
* across environment overlays, and it now carries Compose profiles — so starting it means naming
* one (`--profile local-jpa`) rather than getting it for free with the local overlay. The port
* contract this asserts is unchanged; only the file that owns it is.
* <p>The service lives in the development stack, compose.yaml, under the capability profile
* {@code jpa}: starting it means naming the profile or the service. The port contract this
* asserts is unchanged; only the file that owns it is.
*/
@Test
@Tag("repository-contract")
@@ -108,16 +111,16 @@ class DeveloperExperienceContractTest {
.as("the committed datasource default is host-side, so it must resolve to the loopback")
.isIn("localhost", "127.0.0.1");
Map<?, ?> infra = parseYamlMap(read("docker-compose.infra.yml"));
Map<?, ?> database = requireMap(requireMap(infra, "services"), "db");
Map<?, ?> compose = parseYamlMap(read("compose.yaml"));
Map<?, ?> database = requireMap(requireMap(compose, "services"), "db");
assertThat(requireStringList(database, "ports"))
.as("a host-side run cannot reach a database the compose stack never publishes")
.contains("127.0.0.1:" + hostPort + ":5432");
assertThat(requireStringList(database, "profiles"))
.as(
"the service is profiled, so a developer starts it by naming a lane; without this the "
+ "port assertion above would pass for a service no lane ever brings up")
.contains("local-jpa");
"the service is profiled, so a developer starts it by naming the profile; without this "
+ "the port assertion above would pass for a service nothing ever brings up")
.contains("jpa");
}
@Test
@@ -388,8 +391,7 @@ class DeveloperExperienceContractTest {
@DisplayName("compose 종료 유예 시간은 웹 drain, async 대기, preStop, 여유를 모두 더한 값 이상이다")
void theComposeStopGraceCoversEveryShutdownWaitInSequence() throws IOException {
// given
Map<?, ?> app =
requireMap(requireMap(parseYamlMap(read("docker-compose.yml")), "services"), "app");
Map<?, ?> app = requireMap(requireMap(parseYamlMap(read("compose.yaml")), "services"), "app");
// The web drain is the value this service runs with — APP_SERVER_SHUTDOWN_TIMEOUT's fallback in
// the same Compose service — not a number copied here, so a changed default changes the sum
// (review 2026-11-03 RR-06-08).
@@ -420,7 +422,10 @@ class DeveloperExperienceContractTest {
void composePublishesTheManagementPortOnLoopbackOnly() throws IOException {
// given
List<String> composeFiles =
List.of("docker-compose.yml", "docker-compose.dev.yml", "docker-compose.local.yml");
List.of(
"compose.yaml",
"src/app-bootstrap/compose-lanes/dev.yaml",
"src/app-bootstrap/compose-lanes/prod-smoke.yaml");
// when
List<String> exposed =
@@ -54,7 +54,7 @@ class GraphQlResolverReachabilityTest {
@Test
@DisplayName("the lane sends an authenticated query and inspects the body, not the status")
void theLaneProvesTheRequestPath() {
Path smoke = repositoryRoot().resolve("infra/graphql/smoke/graphql-smoke.sh");
Path smoke = repositoryRoot().resolve("src/app-bootstrap/compose-lanes/smoke/graphql-smoke.sh");
assertThat(Files.exists(smoke))
.as("without a request against /graphql, the resolver gap is invisible to every gate")
@@ -116,7 +116,7 @@ class SecretSourceValidatorTest {
.withInitializer(ctx -> ctx.getEnvironment().setActiveProfiles("prod"))
.withPropertyValues(allRequiredSecretsPresent())
// The Compose Redis lanes' shape: a credential reference, and the variable it names
// holding a public password from infra/redis-sdk/acl. A deployment that copied the
// holding a public password from compose/redis/acl. A deployment that copied the
// lane's environment would carry both into production.
.withPropertyValues(
"APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE="
@@ -42,7 +42,8 @@ public final class ConfigContractPlugin implements Plugin<Project> {
tree.exclude("app-bootstrap/**");
tree.exclude("**/build/**");
}));
// What an operator edits or runs: the root Compose files, the Logback
// What an operator edits or runs: the development Compose file and the lane
// overlays that run the application, the Logback
// configuration, and the Compose lane contract with the smoke wrapper that drives it
// (each lane's activationEnv, the wrapper's CAPABILITIES_OFF). Their APP_ names must
// be registered and read (07-10, RR-06-07), and a lane's other variables must be read
@@ -51,16 +52,17 @@ public final class ConfigContractPlugin implements Plugin<Project> {
// by hand.
task.getOperatorFiles()
.from(
root.file("../compose.yaml"),
root.fileTree(
root.file(".."),
root.file("app-bootstrap/compose-lanes"),
tree -> {
tree.include("docker-compose*.yml");
// The infrastructure stack: its APP_* variables belong to smoke-test
// clients and other services, not to this application.
tree.exclude("docker-compose.infra.yml");
tree.include("*.yaml");
// The lane-only services: their APP_* variables belong to the smoke
// clients, not to this application.
tree.exclude("lane-services.yaml");
}),
root.file("app-bootstrap/src/main/resources/logback-spring.xml"),
root.file("config/runtime/compose-profile-contracts.json"),
root.file("app-bootstrap/compose-lanes/compose-profile-contracts.json"),
root.file("../scripts/run-compose-runtime-smoke.sh"));
task.getRegistryFile().fileValue(root.file("../docs/registries/env-keys.yaml"));
// No module path here: the typed properties come from the configuration metadata on
@@ -59,7 +59,7 @@ public final class RedisTopologyContract {
throw new IllegalStateException(
"redisTopologyTest was selected without "
+ String.join(", ", missing)
+ "; start a lane from infra/redis-sdk and pass -P<key>=<value>.");
+ "; start a lane from src/adapter/outbound/redis-sdk/compose and pass -P<key>=<value>.");
}
}
@@ -60,16 +60,16 @@ public final class RedisTopologyLanePlugin implements Plugin<Project> {
lane -> {
lane.integration();
if ("unset".equals(declaredMode)) {
// The lane needs a running topology from infra/redis-sdk and its coordinates; without
// The lane needs a running topology from redis-sdk/compose and its coordinates; without
// them it can only fail, so the repository's integrationCheck leaves it out and says
// so rather than failing on an input it was never given (review NEW-16).
lane.explicitOnly(
"it needs -Predis.topology.mode=<standalone|sentinel|cluster|tls> and the topology"
+ " coordinates from infra/redis-sdk (redis-sdk-topology.yml passes them)");
+ " coordinates from redis-sdk/compose (redis-sdk-topology.yml passes them)");
}
lane.setTag("redis-topology & lane-" + declaredMode);
lane.setDescription(
"Runs this leaf's Redis contracts against a real topology declared in infra/redis-sdk.");
"Runs this leaf's Redis contracts against a real topology declared in redis-sdk/compose.");
lane.customize(
test -> configureTopologyTask(test, declaredMode, propertyValues, extension));
});
@@ -204,7 +204,7 @@ class EnvContractVerifierTest {
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: APP_LOG_JSON_ENABLED\n type: boolean\n default: true\n");
Path compose = fixture.repositoryRoot().resolve("docker-compose.yml");
Path compose = fixture.repositoryRoot().resolve("compose.yaml");
Files.writeString(compose, "services:\n app:\n environment:\n APP_LOG_JSON_ENABLED: \"true\"\n");
// when
@@ -231,7 +231,7 @@ class EnvContractVerifierTest {
void anOperatorFileKeyMissingFromTheRegistryFails(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Path compose = fixture.repositoryRoot().resolve("docker-compose.yml");
Path compose = fixture.repositoryRoot().resolve("compose.yaml");
Files.writeString(compose, "services:\n app:\n environment:\n APP_UNREGISTERED: x\n");
// when
@@ -257,7 +257,7 @@ class EnvContractVerifierTest {
void anOperatorFileKeyTheConfigurationReadsPasses(@TempDir Path temp) throws Exception {
// given
Fixture fixture = fixture(temp);
Path compose = fixture.repositoryRoot().resolve("docker-compose.yml");
Path compose = fixture.repositoryRoot().resolve("compose.yaml");
Files.writeString(compose, "services:\n app:\n environment:\n APP_REQUIRED: x\n");
// when
@@ -357,7 +357,7 @@ class EnvContractVerifierTest {
fixture.registry(),
Files.readString(fixture.registry())
+ "- name: APP_GHOST_ENABLED\n property: app.ghost.enabled\n type: boolean\n");
Path compose = fixture.repositoryRoot().resolve("docker-compose.yml");
Path compose = fixture.repositoryRoot().resolve("compose.yaml");
Files.writeString(
compose, "services:\n app:\n environment:\n APP_GHOST_ENABLED: \"true\"\n");
@@ -387,7 +387,7 @@ class EnvContractVerifierTest {
Files.writeString(
ghostClasses.resolve(ConfigurationMetadataClasspath.METADATA),
"{\"properties\":[{\"name\":\"app.ghost.enabled\"}]}");
Path compose = fixture.repositoryRoot().resolve("docker-compose.yml");
Path compose = fixture.repositoryRoot().resolve("compose.yaml");
Files.writeString(
compose, "services:\n app:\n environment:\n APP_GHOST_ENABLED: \"true\"\n");
@@ -53,12 +53,12 @@ SSOT다. 설명은 `docs/fileserver/configuration.md`.
## 필요한 마운트
저장 루트(`/var/lib/backend/files`)는 쓰기 가능한 전용 volume이어야 한다. 기본 이미지와 기본
`docker-compose.yml`은 이 모듈이 없으므로 volume도 갖지 않는다(리뷰 07-08). 이 모듈을 고른 서비스가
`compose.yaml`은 이 모듈이 없으므로 volume도 갖지 않는다(리뷰 07-08). 이 모듈을 고른 서비스가
volume을 붙인다.
| 실행 환경 | 붙이는 방법 |
| --- | --- |
| Compose | `-f infra/fileserver/compose/docker-compose.fileserver.yml`을 더한다. `fileserver-data` named volume을 마운트하고, 앱보다 먼저 `fileserver-storage-init`이 앱 이미지 안에서 root로 한 번 돌아 volume 소유자를 이미지의 `app` 계정으로 바꾼다(0750). 새 volume, 재사용한 volume, bind mount 모두 같다 |
| Compose | `-f src/app-bootstrap/compose-lanes/fileserver.yaml`을 더한다(compose lane fixture다. 서비스는 같은 volume 정의를 자기 compose에 둔다). `fileserver-data` named volume을 마운트하고, 앱보다 먼저 `fileserver-storage-init`이 앱 이미지 안에서 root로 한 번 돌아 volume 소유자를 이미지의 `app` 계정으로 바꾼다(0750). 새 volume, 재사용한 volume, bind mount 모두 같다 |
| Kubernetes | PersistentVolumeClaim을 같은 경로에 마운트하고 pod `securityContext.fsGroup`을 앱 그룹으로 둔다(조건: `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」) |
| `docker run` | `-v <volume>:/var/lib/backend/files`. volume 소유자를 이미지의 `app` 계정으로 먼저 맞춘다 |
@@ -34,7 +34,7 @@ mongo-8=mongo@sha256:4b58ebcb1dc7a7b4e84cd8ce9098d48764ae4478876898ff9551acf2ac4
mongo-7=mongo@sha256:4510cf3d7050003e958745adb25d2deb3fb907430716162d9cc1a92eda2a6047
# apache/kafka:4.1.0
kafka=apache/kafka@sha256:bff074a5d0051dbc0bbbcd25b045bb1fe84833ec0d3c7c965d1797dd289ec88f
# redis:7.4 — the cache-redis container lane; the ACL it loads is infra/redis-sdk/acl.
# redis:7.4 — the cache-redis container lane; the ACL it loads is compose/redis/acl.
redis=redis@sha256:b6b6e3dc0c0952737748e55d5d885272840c7e42ba41ab1d5489f693419882f5
# ghcr.io/shopify/toxiproxy:2.12.0
toxiproxy=ghcr.io/shopify/toxiproxy@sha256:9378ed52a28bc50edc1350f936f518f31fa95f0d15917d6eb40b8e376d1a214e