가상화 및 서브 PC 활용

도커 컴포즈(Docker Compose) 기초: yml 파일로 여러 컨테이너 한 번에 실행하기

content59998 2026. 10. 27. 13:17

현대적인 웹 애플리케이션이나 IT 서비스를 구축할 때 단 하나의 컨테이너만으로 모든 시스템을 구동하는 경우는 드뭅니다. 웹 서버, 데이터베이스, 캐시 서버, 백엔드 API 서버 등 다양한 역할의 컨테이너들이 서로 연동되어 하나의 복합적인 서비스를 구성하게 됩니다.

이러한 다중 컨테이너 환경에서 각 컨테이너를 docker run 명령어 하나씩 일일이 포트 지정, 환경 변수 설정, 네트워크 연동까지 수행하며 구동하는 것은 매우 번거롭고 관리상의 오류를 유발하기 쉽습니다.

이러한 복잡한 다중 컨테이너 관리 절차를 단순화해 주는 도구가 바로 도커 컴포즈(Docker Compose)입니다. 단 하나의 docker-compose.yml 설정 파일 안에 필요한 모든 컨테이너 환경을 정의해 두면, 명령어 한 줄로 여러 컨테이너를 동시에 생성하고 실행할 수 있습니다.

본 글에서는 도커 컴포즈의 핵심 개념과 필요성부터 YAML 파일 작성 문법, 그리고 자주 사용하는 핵심 실행 명령어까지 기초부터 단계별로 상세히 알아보겠습니다.

1. 도커 컴포즈(Docker Compose)의 개념과 사용하는 이유

도커 컴포즈는 여러 개의 도커 컨테이너를 선언적으로 정의하고 일괄적으로 다루기 위한 오케스트레이션 도구입니다.

[이미지: 단일 docker-compose.yml 파일 설정을 통해 웹 서버와 데이터베이스 컨테이너가 동시에 구동되는 구조도]

도커 컴포즈를 도입함으로써 얻을 수 있는 대표적인 장점은 다음과 같습니다.

  • 설정의 문서화 및 코드화: 터미널에 복잡하고 길게 입력했던 옵션 파라미터를 .yml 텍스트 파일에 기록하므로 인프라 설정을 코드 형태로 명확하게 관리할 수 있습니다.
  • 단일 명령어로 일괄 제어: 수십 개의 컨테이너로 구성된 서비스라도 단 한 번의 명령어 실행으로 순서에 맞게 동시에 생성 및 정지할 수 있습니다.
  • 자동화된 내부 네트워크 생성: 도커 컴포즈로 실행된 컨테이너들은 자동으로 전용 가상 네트워크에 묶이게 되므로, 각 컨테이너는 컨테이너 이름을 호스트 이름처럼 사용하여 서로 안전하게 통신할 수 있습니다.
  • 개발 및 테스트 환경의 동일성 확보: 프로젝트 팀원 간에 동일한 docker-compose.yml 파일만 공유하면 누구나 즉시 완전히 똑같은 개발 및 실행 환경을 구축할 수 있습니다.

2. docker-compose.yml 파일 기본 구조 및 작성 가이드

도커 컴포즈의 핵심은 docker-compose.yml 파일의 올바른 구성을 이해하는 것입니다. YAML 문법은 띄어쓰기(들여쓰기)에 매우 민감하므로 공백 처리에 유의하여 작성해야 합니다.

다음은 가장 대표적인 웹 서버(Nginx)와 데이터베이스(MySQL)를 함께 구동하는 기초 예시 코드와 항목별 설명입니다.

YAML
 
version: '3.8'

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    restart: always

  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: mysecretpassword
      MYSQL_DATABASE: mydatabase
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

핵심 구성요소 항목 상세 설명

  1. services: 구동하고자 하는 각각의 컨테이너 정의 블록들을 담는 최상위 항목입니다.
  2. image: 컨테이너를 생성할 때 사용할 도커 허브의 이미지 이름과 태그를 지정합니다.
  3. ports: 호스트 컴퓨터와 컨테이너 내부 간의 포트 바인딩 설정을 지정합니다 ([호스트포트]:[컨테이너포트]).
  4. environment: 컨테이너 내부에서 사용할 환경 변수(비밀번호, DB 이름 등)를 선언합니다.
  5. volumes: 데이터 보존을 위한 호스트와 컨테이너 간의 디렉터리 마운트 및 도커 볼륨을 설정합니다.
  6. restart: always: 컨테이너가 비정상 종료되거나 시스템 부팅 시 자동으로 재시작되도록 지정합니다.

3. 도커 컴포즈 실전 실행, 정지 및 상태 관리 명령어

설정 파일 완성이 끝났다면, 해당 파일이 위치한 디렉터리로 이동하여 도커 컴포즈 명령어를 통해 컨테이너들을 제어합니다.

[이미지: 터미널 창에서 docker compose up -d 명령어를 실행하여 서비스들이 백그라운드에서 구동되는 모습]

가장 많이 활용되는 필수 관리 명령어 모음은 다음과 같습니다.

  • 전체 컨테이너 일괄 생성 및 실행 (docker compose up)
    • docker-compose.yml 내용을 읽어 들여 설정된 모든 서비스를 생성하고 시작합니다.
    • 백그라운드 실행 옵션: docker compose up -d (터미널을 계속 사용할 수 있도록 백그라운드로 실행합니다.)
  • 실행 중인 서비스 상태 확인 (docker compose ps)
    • 도커 컴포즈에 의해 그룹으로 묶여 관리되는 컨테이너들의 실행 상태와 포트 정보를 확인합니다.
  • 실행 로그 실시간 확인 (docker compose logs)
    • 모든 컨테이너에서 발생하는 출력 로그를 통합하여 조회합니다.
    • 실시간 추적 옵션: docker compose logs -f
  • 전체 컨테이너 정지 및 삭제 (docker compose down)
    • 구동 중인 서비스 컨테이너와 자동으로 생성되었던 가상 네트워크 환경을 완전히 정지하고 삭제하여 깔끔하게 정리합니다.

자주 묻는 질문 (FAQ)

Q1. docker-compose 명령어와 docker compose 명령어는 차이가 있나요?

A1. 과거에는 별도로 설치하는 Python 기반 스크립트인 docker-compose(하이픈 포함)를 사용했습니다. 그러나 최신 도커 엔진 버전에서는 Docker CLI 내부 전용 플러그인 형태로 통합된 docker compose(공백으로 구분) 사용을 표준으로 공식 권장하고 있습니다.

Q2. YAML 파일 작성 중 yaml.scanner.ScannerError 오류가 발생하는데 원인이 무엇인가요?

A2. 대부분 들여쓰기(Indentation) 규칙을 위반했을 때 발생하는 문법 오류입니다. YAML 파일에서는 탭(Tab) 키 대신 반드시 스페이스바 공백(보통 2칸 또는 4칸)을 일정하게 사용하여 들여쓰기를 맞춰야 합니다.

Q3. docker compose down을 실행하면 데이터베이스에 저장된 데이터도 모두 지워지나요?

A3. 기본적으로 docker compose down 명령어는 컨테이너와 네트워크만 삭제하고 선언된 볼륨(Volume) 데이터는 그대로 유지합니다. 만약 볼륨에 저장된 파일까지 완전히 삭제하고자 한다면 docker compose down -v 옵션을 부여해야 합니다.

결론

도커 컴포즈는 복잡하게 얽힌 다중 컨테이너 애플리케이션 환경을 단 하나의 설정 파일로 관리할 수 있게 도와주는 현대 IT 인프라 관리의 핵심 도구입니다.

명령 줄에 길고 복잡하게 나열되던 옵션들을 docker-compose.yml 파일로 정돈하고, docker compose up -d 명령어 하나로 서비스를 간편하게 제어하는 방식을 적용해 보면 인프라 구축의 생산성이 비약적으로 향상됩니다.

본 가이드에서 배운 작성 문법과 관리 명령어를 바탕으로 자신만의 다중 컨테이너 구성 환경을 구축해 보시기 바랍니다.