# ============================================================================= # 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//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