Docker Compose 사용법 — 여러 컨테이너를 파일 하나로 관리하기

한 줄 요약

Docker Compose는 여러 컨테이너로 된 서비스를 YAML 파일 하나로 정의하고, 명령 한 줄로 함께 실행하는 도구예요.

Docker Compose

---

1. 핵심 개념

1.1 Docker Compose란

Docker Compose는 여러 컨테이너로 구성된 애플리케이션을 정의하고 실행하는 도구예요. 서비스, 네트워크, 볼륨 설정을 하나의 파일에 적어 두고 관리해요.

YAML: 들여쓰기로 구조를 표현하는 설정 파일 형식이에요.

서비스(service): Compose 파일에서 정의하는 컨테이너 단위예요. 웹 앱, DB가 각각 하나의 서비스예요.

 

1.2 왜 중요한가

컨테이너를 여러 개 쓰면 docker run 명령이 길어지고 순서도 신경 써야 해요. Docker Compose를 쓰면 이 설정이 파일로 남아요.

• 실행 방법이 파일로 기록되어 누가 실행해도 같은 구성이 돼요.
• 긴 명령어를 매번 입력하지 않아도 돼요.
• 네트워크가 자동으로 만들어져 서비스 이름으로 서로 접속할 수 있어요.

---

2. 쉽게 이해하기

Docker Compose는 식당 오픈 체크리스트와 같아요.

• 체크리스트 한 장에 주방, 홀, 창고 준비 내용이 적혀 있어요.
• "오픈" 한 번이면 적힌 대로 모두 준비돼요.
• 직원이 바뀌어도 체크리스트가 같으면 같은 상태로 오픈해요.

docker run을 하나씩 실행하는 것이 구두 지시라면, Compose는 문서로 남긴 지시서예요.

---

3. compose.yaml 작성하기

공식 문서 기준 기본 파일 이름은 compose.yaml이에요. 이전 형식인 docker-compose.yml도 하위 호환으로 인식돼요.

아래는 Spring Boot 앱과 MySQL을 함께 실행하는 예시예요.

services:
  app:
    image: <이미지 이름>:<태그>
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://db:3306/appdb
      SPRING_DATASOURCE_USERNAME: appuser
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: appdb
      MYSQL_USER: appuser
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  db-data:

 

3.1 항목별 설명

항목	설명
services	실행할 컨테이너 목록이에요
image	사용할 이미지예요
ports	호스트와 컨테이너 포트를 연결해요
environment	컨테이너에 전달할 환경 변수예요
depends_on	서비스 시작 순서를 정해요
volumes	데이터를 컨테이너 밖에 보관해요
healthcheck	컨테이너가 정상인지 확인하는 명령이에요

 

3.2 서비스 이름으로 접속

Compose는 기본적으로 애플리케이션용 네트워크를 하나 만들어요. 각 서비스는 이 네트워크에 연결되고, 서비스 이름으로 서로 찾을 수 있어요. 그래서 앱에서 DB 주소를 db:3306으로 적었어요.

 

3.3 depends_on 주의점

depends_on만 쓰면 시작 순서만 정해져요. DB가 접속 가능한 상태인지는 기다리지 않아요.

condition: service_healthy를 함께 쓰면, DB의 healthcheck가 성공한 뒤에 앱이 시작돼요.

 

3.4 비밀번호는 .env 파일로 분리

${DB_PASSWORD}처럼 쓰면 같은 폴더의 .env 파일 값이 들어가요.

DB_PASSWORD=<앱 계정 비밀번호>
DB_ROOT_PASSWORD=<루트 비밀번호>

.env 파일은 Git 저장소에 올리지 않도록 .gitignore에 추가해요.

---

4. 자주 쓰는 명령어

# 백그라운드로 전체 실행
docker compose up -d

# 실행 상태 확인
docker compose ps

# 특정 서비스 로그 보기
docker compose logs -f app

# 전체 중지 및 컨테이너·네트워크 삭제
docker compose down

# 볼륨까지 삭제 (데이터가 사라짐)
docker compose down -v

 

docker compose down은 기본적으로 이름 있는 볼륨을 지우지 않아요. -v 옵션을 붙이면 볼륨도 삭제되므로 DB 데이터가 사라져요.

---

5. 핵심 정리

• Docker Compose는 여러 컨테이너 설정을 compose.yaml 하나로 관리해요.
• 서비스끼리는 서비스 이름으로 접속해요.
• depends_on은 순서만 정해요. 준비 완료까지 기다리려면 condition: service_healthy를 써요.
• 비밀번호는 .env 파일로 분리하고 저장소에 올리지 않아요.
• docker compose down -v는 볼륨 데이터까지 삭제해요.

---

6. 추가 정보

version 항목은 쓰지 않아도 돼요

예전 Compose 파일 맨 위에는 version: "3.8" 같은 줄이 있었어요. 공식 문서에 따르면 이 항목은 현재 obsolete(더 이상 사용되지 않음) 상태예요. 넣으면 경고가 표시되고, Compose는 항상 최신 스키마로 파일을 검증해요.

docker-compose와 docker compose

• docker-compose(하이픈): Python으로 작성된 Compose v1 명령이에요.
• docker compose(띄어쓰기): Go로 작성된 Compose v2 이후 명령이에요.

공식 문서 기준 현재 지원되는 버전은 Compose v2와 v5예요.

관련 글

• 도커(Docker) 개념 정리 — 잘못 쓰면 이렇게 됩니다