Docker Compose 컨테이너끼리 통신이 안 될 때

핵심 요약

Compose에서 앱이 DB를 localhost:5432로 부르면 자기 컨테이너를 가리켜 실패한다. 같은 Compose 네트워크에 있는 컨테이너는 서비스 이름(예: db:5432)으로 서로를 찾는다. depends_on은 시작 순서만 보장할 뿐 "준비 완료"는 보장하지 않는다.

1. 서비스명으로 연결

services:
  app:
    environment:
      DATABASE_URL: postgres://user:pw@db:5432/mydb  # localhost 아님
  db:
    image: postgres:16

2. 준비 대기

depends_on은 "컨테이너 시작"만 — DB가 연결 받을 준비는 별개
healthcheck + depends_on: condition: service_healthy로 진짜 준비 대기
앱에 재시도 로직을 두는 게 가장 견고

3. 함정

호스트에서 접속하려면 ports:로 매핑, 컨테이너끼리는 매핑 없이 서비스명으로
다른 Compose 프로젝트면 네트워크가 달라 못 본다 — external 네트워크 공유
DB 시작 직후 연결 시도는 실패 — 재시도/healthcheck 필요

자주 묻는 질문

왜 localhost로는 DB에 못 붙나요?

각 컨테이너의 localhost는 자기 자신입니다. 다른 컨테이너는 같은 네트워크의 서비스 이름(db 등)으로 접근해야 합니다.

depends_on을 걸었는데 DB 연결이 실패해요.

depends_on은 시작 순서만 보장합니다. DB가 연결을 받을 준비가 되기 전 앱이 붙으면 실패하니, healthcheck 조건이나 앱의 재시도를 추가하세요.