도커 컴포즈란? yml 파일 읽는 법부터 차근차근
복잡해 보이는 들여쓰기, 알고 보면 규칙이 단순합니다
- 도커 컴포즈란 여러 컨테이너를 하나의 파일로 한 번에 관리하는 도구입니다.
- compose.yml은 services, volumes, networks 같은 큰 항목으로 구성됩니다.
- 들여쓰기(indent) 두 칸이 곧 부모-자식 관계를 나타냅니다.
- docker compose up 한 줄로 여러 컨테이너를 동시에 실행할 수 있습니다.
웹 서버, 데이터베이스, 캐시 서버를 각각 docker run 명령으로 따로따로 켜본 적 있나요? 명령어가 세 줄, 네 줄로 늘어나고 옵션도 매번 기억해야 해서 번거롭습니다.
도커 컴포즈란 이 반복 작업을 파일 하나로 끝내는 도구입니다. yml 파일에 필요한 컨테이너 구성을 미리 적어두면, 명령어 한 줄로 전부 켜고 끌 수 있습니다.
처음 yml 파일을 열어보면 들여쓰기만 가득해서 막막할 수 있습니다. 이 글에서는 그 구조를 한 줄씩 뜯어가며, 어떤 규칙으로 읽으면 되는지 알려드립니다.
이전 글에서 이미지와 컨테이너 개념을 다뤘다면, 이번엔 그 컨테이너들을 여러 개 한꺼번에 관리하는 실전 도구로 넘어갑니다.
도커 컴포즈란 무엇인가 – 왜 필요할까
도커 컴포즈란 여러 개의 컨테이너로 이루어진 애플리케이션을 하나의 설정 파일로 정의하고, 명령어 하나로 실행·중지할 수 있게 해주는 도구입니다.
보통 실제 서비스는 웹 서버 하나만 돌지 않습니다. 웹 서버, 데이터베이스, 캐시, 관리자 페이지처럼 여러 컨테이너가 서로 통신하며 함께 동작합니다.
이 여러 컨테이너를 docker run으로 하나씩 켜려면 포트 번호, 볼륨 경로, 환경 변수 옵션을 매번 정확히 입력해야 합니다. 실수로 하나라도 빠뜨리면 서비스 전체가 오작동합니다.
컴포즈 파일은 일종의 “레시피북”입니다. 냉장고 문에 붙여놓은 요리 순서표처럼, 어떤 컨테이너를 어떤 설정으로 몇 개 띄울지 한 곳에 정리해두는 셈입니다. 새로 합류한 팀원도 파일 하나만 받으면 똑같은 환경을 그대로 재현할 수 있습니다.
도커 컴포즈란 결국 “반복되는 docker run 명령을 문서화하고 자동화하는 도구”라고 정리할 수 있습니다. 개발 환경 구축뿐 아니라 테스트, 로컬 배포에도 널리 쓰입니다.
실무에서는 compose.yaml 파일 하나만 깃(Git) 저장소에 올려두고, 팀원 전체가 docker compose up 명령 하나로 같은 개발 환경을 켭니다.
yml 파일 기본 구조 읽는 법
yml(또는 yaml) 파일은 프로그래밍 코드가 아니라 데이터를 계층적으로 표현하는 표기법입니다. 중괄호나 세미콜론 없이 오직 들여쓰기와 콜론(:)만으로 구조를 나타냅니다.
규칙은 딱 두 가지입니다. 첫째, 같은 들여쓰기 깊이는 같은 그룹입니다. 둘째, 한 칸 더 들여쓰면 그 위 항목의 하위 항목이라는 뜻입니다. 보통 스페이스 2칸을 한 단계로 씁니다.
최상위(들여쓰기 없는) 항목은 보통 services, volumes, networks 세 가지입니다. services는 실행할 컨테이너 목록, volumes는 데이터 저장 공간, networks는 컨테이너 간 통신 규칙을 정의합니다.
yml 파일에서는 탭(Tab) 키를 절대 쓰면 안 됩니다. 반드시 스페이스로만 들여쓰기를 해야 하며, 탭이 하나라도 섞이면 파싱 오류가 나서 컴포즈가 실행되지 않습니다.
편집기(VS Code 등)에서 YAML 확장 프로그램을 설치하면 들여쓰기가 틀렸을 때 빨간 줄로 바로 알려줘서 실수를 크게 줄일 수 있습니다.
services 항목 하나하나 뜯어보기
compose.yml에서 가장 중요한 부분은 services 항목입니다. 여기에 실행하고 싶은 컨테이너를 하나씩 이름을 붙여 등록합니다.
예를 들어 웹 서버 컨테이너 이름을 web이라고 짓고, 그 아래 한 단계 들여써서 image, ports, environment 같은 세부 설정을 적습니다. image는 어떤 이미지를 쓸지, ports는 어떤 포트를 외부에 열지 정합니다.
ports는 “호스트포트:컨테이너포트” 형식으로 씁니다. 예를 들어 8080:80은 내 컴퓨터의 8080번 포트로 접속하면 컨테이너 내부 80번 포트로 연결된다는 뜻입니다.
services 바로 아래 한 칸 들여써서 web, db처럼 각 컨테이너에 이름을 붙이면 됩니다. 이 이름은 컨테이너끼리 서로를 찾을 때 주소처럼도 쓰입니다.
environment 항목에는 컨테이너 안에서 쓸 환경 변수를 지정합니다. 데이터베이스 비밀번호나 접속 정보를 여기에 적어두면 컨테이너 실행 시 자동으로 반영됩니다.
depends_on 항목을 쓰면 컨테이너 실행 순서를 정할 수 있습니다. 예를 들어 웹 서버가 데이터베이스보다 나중에 켜지게 하고 싶을 때 이 옵션을 씁니다.
도커 컴포즈란 실제로 어떻게 실행되나 – 명령어 흐름
구조를 이해했다면 이제 실제로 실행하는 흐름을 살펴보겠습니다. 도커 컴포즈란 결국 이 파일을 읽어서 그 안에 적힌 대로 컨테이너를 순서대로 만들어주는 도구입니다.
compose.yml이 있는 폴더에서 터미널을 열고 docker compose up을 입력하면, services에 적힌 컨테이너들이 한꺼번에 생성되고 실행됩니다. -d 옵션을 붙이면 백그라운드에서 조용히 실행됩니다.
실행 중인 상태를 확인하려면 docker compose ps를 입력합니다. compose 파일에 정의된 컨테이너들만 따로 모아서 보여주기 때문에, 전체 docker ps보다 훨씬 보기 편합니다.
docker compose logs -f 명령을 쓰면 모든 컨테이너의 로그를 한 화면에서 실시간으로 볼 수 있습니다. 컨테이너마다 따로 로그를 확인할 필요가 없어 문제 파악이 훨씬 빠릅니다.
종료할 때는 docker compose down을 입력합니다. 이 명령은 실행 중인 컨테이너를 전부 멈추고 삭제하지만, volumes에 저장된 데이터는 기본적으로 남겨둡니다.
설정 파일을 수정한 뒤에는 docker compose up –build를 실행해 변경된 내용을 반영한 이미지로 다시 빌드해야 합니다. 단순히 up만 다시 실행하면 예전 이미지가 그대로 쓰일 수 있습니다.
이렇게 up, ps, logs, down 네 가지 명령만 익혀도 컴포즈 사용의 80% 이상을 커버할 수 있습니다.
컴포즈 파일 작성 시 자주 하는 실수
가장 흔한 실수는 들여쓰기 깊이를 잘못 맞추는 것입니다. 스페이스 한 칸만 어긋나도 전혀 다른 계층으로 해석돼 “예상과 다른 설정이 적용됐다”는 상황이 생깁니다.
두 번째는 포트 충돌입니다. 여러 서비스에서 같은 호스트 포트(예: 8080)를 동시에 쓰려고 하면 나중에 실행되는 컨테이너가 시작하지 못합니다. 서비스마다 다른 호스트 포트를 지정해야 합니다.
세 번째는 환경 변수 파일 관리 실수입니다. 비밀번호 같은 민감한 값을 compose.yml에 그대로 적어 깃허브에 올리는 경우가 있는데, .env 파일로 분리하고 .gitignore에 등록하는 게 안전합니다.
compose.yml 문법이 맞는지 실행 전에 확인하고 싶다면 docker compose config 명령을 써보세요. 실제로 컨테이너를 켜지 않고, 도커가 이 파일을 어떻게 해석했는지 최종 결과만 미리 보여줘서 오타를 빠르게 잡을 수 있습니다.
네 번째는 오래된 문법(version: ‘3’ 같은 최상위 버전 표기)을 그대로 복사해 쓰는 경우입니다. 최신 컴포즈는 이 항목 없이도 잘 작동하며, 공식 문서도 최신 Compose Specification 방식을 권장합니다.
이런 실수들은 대부분 파일을 몇 번 직접 고쳐보면서 자연스럽게 줄어듭니다. 처음에는 서비스 한두 개짜리 작은 파일부터 시작해보는 걸 추천합니다.
FAQ
기능은 거의 같지만 docker-compose(하이픈)는 예전 독립 프로그램이고, docker compose(스페이스)는 도커에 내장된 최신 방식입니다. 신규 사용자는 후자를 쓰는 게 권장됩니다.
둘 다 인식됩니다. 최신 버전은 compose.yaml을 우선 찾고, 없으면 docker-compose.yml을 사용합니다.
네, 문법 오류가 있으면 docker compose up 실행 시 어느 줄에서 문제가 생겼는지 오류 메시지로 알려줍니다.
필수는 아니지만, 포트나 볼륨 설정이 복잡해지면 컨테이너 하나여도 컴포즈로 관리하는 게 명령어를 매번 치는 것보다 편합니다.
가능합니다. docker compose restart 서비스이름처럼 특정 서비스 이름만 지정하면 그 컨테이너만 재시작됩니다.
📖 핵심 용어 미니 사전
본문에 나온 용어가 낯설다면 아래에서 먼저 확인해보세요.
들여쓰기로 데이터의 계층 구조를 표현하는 사람이 읽기 쉬운 데이터 표기법입니다.
compose 파일에서 실행할 컨테이너 목록을 정의하는 최상위 항목입니다.
컨테이너 간 실행 순서를 지정하는 compose 파일 옵션입니다.
비밀번호 같은 민감한 값을 코드와 분리해 보관하는 환경 변수 파일입니다.
🔗 공식 자료
📖 출처
- Docker Docs, “Docker Compose” – docs.docker.com/compose/
- Docker Docs, “Compose file reference” – docs.docker.com/reference/compose-file/
- Docker Docs, “Docker Compose Quickstart” – docs.docker.com/compose/gettingstarted/
- Docker Docs, “How Compose works” – docs.docker.com/compose/intro/compose-application-model/
도커 컴포즈란 여러 컨테이너를 하나의 yml 파일로 정의하고 명령어 한 줄로 관리하는 도구입니다. 들여쓰기 두 칸이 부모-자식 관계라는 규칙만 알면 yml 파일을 읽는 게 훨씬 쉬워집니다.
