docker compose는 언제 필요할까: 앱과 DB를 함께 띄우는 개발 환경 만들기

docker compose는 앱 하나만 실행할 때보다 앱과 DB, Redis 같은 여러 서비스를 함께 띄울 때 빛이 납니다.

핵심은 로컬 개발 환경을 명령 하나로 반복 가능하게 만드는 것입니다. 이 글은 Docker Compose 공식 문서를 기준으로 service, network, volume, env_file, depends_on 한계, 개발용과 운영용 차이를 정리합니다.

docker compose가 필요한 순간

앱 컨테이너 하나만 실행한다면 `docker run`으로도 충분할 수 있습니다. 하지만 앱이 PostgreSQL, Redis, LocalStack 같은 의존 서비스를 함께 필요로 하면 매번 명령을 직접 조합하기 어렵습니다.

app
  -> postgres
  -> redis
  -> mailhog

app
  -> postgres
  -> redis
  -> mailhog

compose는 이런 여러 실행 단위를 하나의 YAML 파일에 적고, `docker compose up`으로 함께 띄우게 해 줍니다.

가장 작은 compose.yml 예제

아래 예제는 web 앱과 PostgreSQL을 함께 실행합니다. compose 안에서 각 항목은 service입니다.

services:
  web:
    build: .
    ports:
      - "8080:8080"
    env_file:
      - .env
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

services:
  web:
    build: .
    ports:
      - "8080:8080"
    env_file:
      - .env
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

이 파일이 있으면 팀원이 같은 구조의 개발 환경을 훨씬 쉽게 띄울 수 있습니다.

service 이름은 네트워크 안의 주소가 된다

Compose는 기본 네트워크를 만들고, 서비스 이름으로 서로 접근할 수 있게 합니다. 그래서 web 컨테이너 안에서는 DB host를 `localhost`가 아니라 `db`로 보는 경우가 많습니다.

DATABASE_URL=postgresql://app:app@db:5432/app

DATABASE_URL=postgresql://app:app@db:5432/app

컨테이너 안의 localhost는 자기 자신입니다. 이 차이를 모르면 앱 컨테이너가 DB에 연결하지 못하는 문제를 자주 만납니다.

volume은 데이터 보존을 위한 장치

컨테이너는 지우고 다시 만들 수 있습니다. 하지만 DB 데이터는 개발 중에도 유지하고 싶을 수 있습니다. 이때 named volume을 사용합니다.

services:
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

services:
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

반대로 테스트마다 깨끗한 DB가 필요하다면 volume을 일부러 지우거나 별도 compose 파일을 두는 방식이 낫습니다.

depends_on은 준비 완료를 보장하지 않는다

`depends_on`은 시작 순서를 제어하는 데 도움이 됩니다. 하지만 DB 프로세스가 완전히 준비되어 쿼리를 받을 수 있는지까지 항상 보장한다고 보면 위험합니다.

services:
  web:
    depends_on:
      - db

services:
  web:
    depends_on:
      - db

앱이 시작 직후 DB 연결에 실패한다면 healthcheck, 재시도 로직, 마이그레이션 실행 순서를 함께 봐야 합니다.

개발용 compose와 운영용 compose는 다르다

개발용 compose는 빠른 실행과 재현성이 목적입니다. 운영 배포는 보안, 확장, 관측, secret 관리, 롤링 업데이트 같은 요구가 더 큽니다. 그래서 로컬 compose 파일을 그대로 운영 표준으로 보는 것은 위험합니다.

• 개발용: 포트 노출, bind mount, 로컬 .env 사용이 많다
• 운영용: secret 관리, 로그, 모니터링, 스케일링, 배포 전략이 필요하다
• compose는 로컬 개발과 작은 환경에는 좋지만 운영 요구를 따로 검토해야 한다

실무 체크리스트

1. 앱 외에 DB, 캐시, 메시지 브로커가 함께 필요한지 확인한다
2. 서비스 이름을 네트워크 host로 쓰는 구조를 이해한다
3. 데이터를 보존해야 하면 volume을 명시한다
4. 환경 변수는 env_file로 분리하되 민감 정보 커밋을 피한다
5. depends_on만 믿지 말고 readiness와 retry를 함께 설계한다

정리

docker compose는 이름만 외우는 것보다 어떤 문제를 줄이기 위한 도구인지 보는 편이 좋습니다. 이 글에서는 공식 문서 기준으로 핵심 개념, 자주 하는 실수, 실무 판단 기준을 함께 정리했습니다.

함께 보면 좋은 내부 글은 Dockerfile layer cache는 왜 중요할까, Spring Boot profile은 언제 나눠야 할까, SQL 인덱스는 왜 빠를까입니다. 외부 기준은 Docker Docs – Docker Compose overview, Docker Docs – Compose file services, Docker Docs – Control startup order를 확인했습니다.