T-04 로컬 실행 환경 검증

[ff1451]

Refs #16
Base: feat/t01-common-foundation (#56) — T-01 위에 stack.

배경

워크플로우 7단계("Executable Environment 검증")를 실제로 수행했다. "부팅 → 마이그레이션 → /health 200"이 로컬에서 재현되는지 확인하고, 겪은 문제를 README에 남긴다.

변경

• docker-compose.yml — 로컬 Postgres 16-alpine. 호스트 포트는 COMPOSE_POSTGRES_PORT로 오버라이드 가능(기본 5432).
• README.md (신규) — 실행 절차, 테스트 실행, 흔히 겪는 문제.

application-local.yml을 추가하지 않은 이유

기존 태스크 계획에는 있었지만, 실제로 보니 .env + springboot4-dotenv(developmentOnly)가 이미 이 역할을 하고 있다. .env.example에 로컬에 필요한 오버라이드(DB_*, REFRESH_TOKEN_COOKIE_SECURE, SWAGGER_SERVER_URL 등)가 전부 문서화되어 있어서, Spring profile을 추가로 얹으면 "로컬 설정을 하는 방법이 두 가지"가 된다. 기존 auth·member 팀이 만든 방식을 그대로 따랐다.

로컬에서 실제로 부딪힌 문제

이 머신에 홈브루 postgresql@18 서비스가 이미 5432를 점유하고 있었다. Docker 컨테이너도 5432에 붙었지만, macOS에서 특정 바인드(127.0.0.1:5432, 네이티브)와 와일드카드 바인드(*:5432, Docker)가 공존해 localhost 연결이 네이티브 쪽으로 갔다. 그 Postgres에는 postgres role이 없어서 Flyway가 FATAL: role "postgres" does not exist로 실패했다.

해결: docker-compose.yml에 COMPOSE_POSTGRES_PORT 오버라이드를 추가하고 5433으로 재현 — 정상 동작 확인. 기본값은 5432로 유지했다(충돌 없는 게 일반적인 경우이므로), 충돌 시 대응법을 README에 남겼다.

검증

cp .env.example .env  # JWT_SECRET 채움
COMPOSE_POSTGRES_PORT=5433 docker compose up -d
./gradlew bootRun

Flyway: Successfully applied 6 migrations to schema "public", now at version v6
Tomcat started on port 8080
Started BcsdInternalApiV2Application in 4.59 seconds

$ curl -w " (HTTP %{http_code})\n" http://localhost:8080/health
OK (HTTP 200)

./gradlew test 전체 통과(T-01의 28개 테스트, 변경 없음).

참고로 남겨둘 것 (범위 밖)

부팅 로그에 springdoc 경고가 떴다: SpringDoc /v3/api-docs endpoint is enabled by default. To disable it in production... — ADR-017(운영에서 springdoc 인증 뒤에 두기)이 아직 적용 안 됐다는 뜻인데, 이건 별도 태스크 영역이라 손대지 않았다.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 850b0670-1f9f-4455-9292-f37eddb2c6f0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}