도커 컴포즈 사용법: yml 작성부터 컨테이너 실행까지

도커 컴포즈는 여러 컨테이너로 구성된 애플리케이션을 단 하나의 설정 파일로 정의하고 관리할 수 있도록 돕는 도구입니다. 복잡한 명령어를 매번 터미널에 입력하지 않고도 단일 명령으로 모든 서비스를 한 번에 생성하고 제어할 수 있습니다.

웹 서버와 데이터베이스처럼 서로 긴밀하게 연결되어 동작해야 하는 시스템을 구축할 때 도커 컴포즈 사용법을 익혀두면 작업 효율이 크게 높아집니다. 각 컨테이너의 포트 설정, 환경 변수, 볼륨 연결 등을 하나의 파일 안에 체계적으로 정리할 수 있기 때문입니다.

개별 컨테이너를 일일이 실행하며 발생하기 쉬운 네트워크 설정 오류나 누락 문제를 줄일 수 있어서 실무와 개인 프로젝트 모두에서 널리 쓰입니다. 이번 안내에서는 기본 개념부터 설정 파일 작성 및 관리 명령어까지 단계별로 설명해 드립니다.

도커 컴포즈 개념과 필요성

기본적인 도커 환경에서는 애플리케이션을 실행하기 위해 매번 docker run 명령어를 포트, 볼륨, 환경 변수 옵션과 함께 입력해야 합니다. 만약 백엔드 서버, 프론트엔드, 데이터베이스가 분리되어 있다면 각각의 컨테이너를 따로 실행하고 가상 네트워크로 묶어주는 과정이 상당히 번거로워집니다.

이 도구는 이러한 다중 컨테이너 구성을 코드 형태의 파일로 기록하여 인프라를 문서화하는 역할을 수행합니다. 설정 파일만 공유하면 다른 작업자나 새로운 서버 환경에서도 동일한 구조의 컨테이너 생태계를 손쉽게 재현할 수 있다는 점이 큰 장점입니다.

기본 설정 파일 작성 방식

컴포즈 환경을 구축하려면 프로젝트 루트 디렉터리에 compose.yaml 혹은 docker-compose.yml 파일 작성을 진행해야 합니다. 이 파일은 들여쓰기를 기준으로 계층 구조를 인식하므로 탭 대신 일관된 스페이스 공백을 사용하는 것이 중요합니다.

가장 핵심이 되는 최상위 키는 services이며, 이 아래에 구동할 각 컨테이너의 이름을 정의하게 됩니다. 각 서비스 항목 안에는 사용할 베이스 이미지(image), 호스트와 컨테이너 간의 포트 연결(ports), 데이터 보존을 위한 저장소 연결(volumes), 실행 환경에 필요한 변수(environment) 등을 차례대로 기재합니다.

일반 명령어와 컴포즈 방식 비교

단일 컨테이너 방식과 컴포즈를 활용한 방식은 관리 편의성 면에서 명확한 차이를 보입니다. 복잡한 명령어를 터미널 히스토리에서 찾지 않고 파일 기반으로 다룰 수 있다는 점이 핵심 차이점입니다.

위 표에서 알 수 있듯이 설정 정보가 파일로 격리되어 관리되기 때문에 인프라 형상 관리가 가능해집니다. 버전 관리 시스템(Git 등)을 통해 변경 내역을 추적할 수 있어 협업 시 혼선을 예방할 수 있습니다.

도커 컨테이너 실행 및 제어 절차

설정 파일 작성이 끝났다면 터미널에서 docker compose up 명령을 입력하여 도커 컨테이너 실행을 진행할 수 있습니다. 백그라운드 환경에서 지속해서 서비스를 띄워두고 싶다면 뒤에 -d 옵션을 추가하여 분리 모드로 구동하는 방식을 택합니다.

현재 작동 중인 서비스 상태를 확인하려면 docker compose ps 명령을 사용합니다. 특정 서비스의 표준 출력 로그를 확인하거나 오류를 추적할 때는 docker compose logs 명령에 서비스명을 붙여 호출하면 필요한 기록만 선별하여 검토할 수 있습니다.

도커 컴포즈 환경 변수 파일 연동과 분리 방법

실제 운영 환경에서 도커 컴포즈 관리를 효율화하려면 설정값과 민감한 보안 정보를 파일에서 분리해야 합니다. 데이터베이스 암호나 API 키 같은 정보를 설정 파일 내부에 직접 적으면 보안 사고의 원인이 될 수 있습니다. 기본적으로 컴포즈는 동일한 경로에 위치한 .env 파일을 자동으로 탐색하여 변수 값을 치환합니다.

체계적인 도커 컴포즈 사용법을 익히기 위해서는 env_file 지시어를 활용해 서비스별로 서로 다른 환경 파일을 지정하는 방식을 이해해야 합니다. 개발용 설정과 배포용 설정을 파일 단위로 분리하면 동일한 구조를 유지하면서도 환경 전환이 수월해집니다. 이를 통해 설정 변경 시마다 코드를 고칠 필요 없이 유연한 설정 관리가 가능합니다.

컨테이너 실행 순서 제어와 의존성 정의 기법

여러 컨테이너가 연동될 때는 특정 서비스가 완전히 준비된 후에 후속 서비스가 기동되도록 순서를 조율해야 합니다. 예를 들어 웹 서버는 데이터베이스가 정상적으로 열리기 전에는 정상 작동하기 어렵습니다. 이러한 실행 순서는 depends_on 속성을 지정하여 손쉽게 통제할 수 있습니다.

더 안정적인 구동 흐름을 원한다면 yml 파일 작성 단계에서 condition 속성과 healthcheck 옵션을 결합하는 방식이 권장됩니다. 단순 실행 상태가 아니라 포트 응답이나 헬스체크 통과를 확인한 뒤 다음 서비스를 띄울 수 있어 구동 오류를 줄여줍니다. 이를 통해 도커 컴포즈 기반의 다중 컨테이너 환경을 한층 더 안정적으로 통제하게 됩니다.

데이터 영속성을 위한 볼륨과 네트워크 구축

컨테이너는 기본적으로 수명이 다하면 내부 데이터가 초기화되는 무상태 구조를 가집니다. 데이터베이스 저장 파일이나 사용자 업로드 파일처럼 보존해야 하는 자료는 볼륨(volumes) 지시어로 호스트 경로에 연결해야 안전합니다. 명명된 볼륨(named volume)을 사용하면 엔진 레벨에서 저장 영역을 체계적으로 분리하여 관리할 수 있습니다.

네트워크 계층 역시 보안성을 위해 목적별로 세분화하여 분리하는 설계가 유용합니다. 외부 트래픽을 직접 받는 프론트엔드와 내부에서만 통신하는 데이터베이스를 별도 서브넷으로 격리하면 불필요한 접근 경로를 차단할 수 있습니다. 이러한 격리 설정을 마치고 도커 컨테이너 실행 명령을 내리면 설계된 네트워크 토폴로지가 자동으로 구현됩니다.

도커 컴포즈 실무 환경에서 자주 묻는 질문

Q. 설정 파일의 이름을 기본 파일명 외에 다른 이름으로 지정할 수 있나요?
A. 네, -f 옵션을 활용하면 다른 이름의 파일이나 다른 경로의 파일을 지정하여 실행할 수 있습니다. 예를 들어 개발용과 운영용 파일을 분리한 뒤 상황에 맞춰 해당 옵션으로 파일을 지정해 구동하면 유용합니다.

Q. 특정 컨테이너 하나만 다시 빌드하고 재실행하려면 어떻게 해야 하나요?
A. 전체를 내릴 필요 없이 docker compose up --build 서비스명 명령을 입력하면 지정한 서비스만 이미지를 다시 빌드하고 재시작합니다. 다른 컨테이너의 중단 없이 빠르게 변경 사항을 반영할 때 효과적입니다.

Q. docker compose stop과 down은 어떤 동작 차이가 있나요?
A. stop 명령은 컨테이너 구동만 일시적으로 중단시키며 컨테이너와 네트워크 상태를 그대로 보존합니다. 반면 down 명령은 컨테이너를 중지함과 동시에 컨테이너 인스턴스와 생성된 네트워크 리소스를 완전히 삭제합니다.

복잡해지는 애플리케이션 아키텍처에서 도커 컴포즈를 활용해 인프라 정의를 명문화하는 작업은 대단히 유용합니다. 파일 하나에 전체 서비스의 연결 구조와 저장소 정책을 명시해 두면 배포 환경의 일관성을 손쉽게 확보할 수 있습니다.

처음에는 간단한 웹과 데이터베이스 조합으로 시작하여 점진적으로 헬스체크와 전용 네트워크 같은 상세 설정을 확장해 보시길 권장합니다. 규격화된 구성을 차근차근 갖춰 나간다면 개발 생산성과 시스템 안정성을 동시에 높일 수 있습니다.

이 글은 일반적인 소프트웨어 도구 사용법 및 정보 제공을 목적으로 작성되었습니다. 도커 소프트웨어 버전 변경이나 개별 시스템 환경에 따라 명령어와 세부 동작에 차이가 있을 수 있으므로 최신 공식 기술 문서를 참조하시길 권장합니다.

자주 묻는 질문

지금까지 컨테이너 기반 서비스를 구조화하고 효율적으로 통제하는 핵심 방법들을 살펴보았습니다. 인프라 설정을 텍스트 파일로 명문화해 두면 환경 이전이나 배포 과정에서 발생할 수 있는 휴먼 에러를 방지하는 데 큰 도움이 됩니다.

기본적인 구조를 익힌 뒤 환경 변수 파일 연동이나 서비스 종속성 관리 옵션을 차근차근 적용해 보시길 바랍니다. 운영 중인 서버 구성에 맞춰 필요한 옵션을 하나씩 확장해 나간다면 안정적인 개발 환경을 유지할 수 있습니다.