ADR-004 docker-compose 파일 분리 전략 (Single Writer 충돌 방지)
- 상태: 채택 (2026-07-03 senior-pm #4 반영 개정)
- 날짜: 2026-07-03
- 근거: PRD FR-9 / 지시(⑦⑧과 compose 공동 수정) / senior-pm 정합 검증 #4 / TDD “Possible Solutions — docker-compose 파일 소유”
맥락
docker-compose.yml은 본 과제(⑤)뿐 아니라 ⑦(backend 다중 인스턴스 + LB)·⑧(dev/prod 스택 분리)의 공동 수정 대상이다. 한 파일에 인프라·관측 스택을 모두 추가하면 Single Writer 충돌(머지 컨플릭트)이 불가피하다.
추가로 senior-pm 4가 지적: ⑤가 docker-compose.infra.yml에 데이터스토어(mysql/redis/kafka/mongo)를 정의하면 ⑧ base compose도 동일 데이터스토어를 정의하므로 -f 병합 시 중복 서비스가 생기고, 특히 서비스명 mongo(⑤) vs mongodb(⑧) 불일치로 mongo 컨테이너가 2개 뜬다.
결정
데이터스토어의 단일 소유자는 ⑧ base compose로 확정한다. ⑤는 데이터스토어를 정의하지 않고, 관측 전용 compose 2개로 분리한다. docker compose -f 병합으로 합친다.
| 파일 | 소유 과제 | 내용 |
|---|---|---|
docker-compose.yml (기존) | 공용(유지) | minio·mock-pg·mock-servers·mailhog — ⑤는 건드리지 않음 |
| base compose (데이터스토어) | ⑧ | mysql·mongodb·redis·kafka — ⑤는 정의하지 않고 참조만 |
docker-compose.observability.yml (신규) | ⑤ | OTel Collector·Tempo·Loki·Prometheus·Grafana (관측 백엔드) |
docker-compose.observability-agents.yml (신규) | ⑤ | mysqld_exporter·redis_exporter·kafka_exporter·Kafka UI (⑧ 데이터스토어에 접속) |
docker-compose.scale.yml (예정) | ⑦ | 앱 인스턴스 N개·nginx LB |
docker-compose.dev.yml/.prod.yml (예정) | ⑧ | 환경별 override |
병합 예: docker compose -f docker-compose.yml -f <⑧ base> -f docker-compose.observability.yml -f docker-compose.observability-agents.yml up
근거
- 데이터스토어 중복 정의 0 — 단일 소유자(⑧)만 데이터스토어를 정의 → mongo 이중화·서비스명 불일치 해소.
- 파일 소유 = 과제 소유 — 각 과제가 자기 파일만 만지므로 병렬 진행해도 compose 머지 충돌 0. ⑤ 관측 파일 2개도 서로 disjoint.
- 관측 스택 down 독립성 —
docker-compose.observability*.yml down만으로 관측 스택을 끄고 앱·데이터스토어는 유지(무중단 롤백). - 명명 규약 통일 — 데이터스토어 서비스명은 ⑧ 기준
mongodb. ⑤ exporter/config는 이 이름을 참조.
대안 (미채택)
- ⑤가 데이터스토어도
docker-compose.infra.yml로 소유: ⑧과 중복 정의·mongo 이중화. 미채택(senior-pm #4). - 기존
docker-compose.yml에 전부 추가: ⑦⑧과 Single Writer 충돌. 미채택. - profiles로 한 파일 내 분기: 한 파일이라 여전히 공동 수정 대상. 미채택.
영향
- INFRA-01=
docker-compose.observability-agents.yml(exporter+Kafka UI), INFRA-02=docker-compose.observability.yml(관측 백엔드) — 서로 다른 파일이라 같은 wave 병렬 안전. - ⑤ exporter는 ⑧ base compose(데이터스토어)를 런타임 선행 조건으로 요구 — 공유 네트워크로 접속.
- 병합 오케스트레이션(
.env·Makefile·README)은 INFRA-05 통합 티켓이 단독 소유(공통 파일 단일 writer). - ⑦⑧ 착수 시 이 ADR을 인용해 자기 override/base 파일을 추가한다.