작성 기준: Docker Compose 실무 가이드
작성일: 2026-04-29 | 환경: Docker Engine, Compose V2
1. docker-compose란?
docker-compose는 여러 개의 Docker 컨테이너를 하나의 YAML 파일로 정의하고, 이를 통해 전체 애플리케이션 스택을 한 번에 관리할 수 있게 해주는 도구입니다.
복잡한 멀티 컨테이너 환경(예: Web + DB + Redis)을 단일 명령어로 오케스트레이션할 수 있어, 인프라를 코드로 관리하는 IaC(Infrastructure as Code) 환경을 구축하는 데 필수적입니다.
💡 핵심 장점
- 단일 명령 제어: 모든 서비스를 한 번에 시작, 중지, 삭제 가능
- 환경 일관성: 개발, 테스트, 운영 환경을 동일한 YAML로 유지
- 네트워크 자동화: 컨테이너 간 전용 네트워크를 자동으로 생성 및 연결
2. 설치 및 확인
최근 Docker Desktop이나 최신 Docker Engine에는 docker compose 명령어가 기본 포함되어 있습니다.
[버전 확인]
$ docker compose version
3. 기본 문법 및 주요 명령어
모든 설정은 프로젝트 루트 디렉토리의 docker-compose.yml 파일을 기준으로 동작합니다.
| 명령어 | 설명 |
|---|---|
pull |
설정된 모든 서비스의 이미지를 최신 버전으로 다운로드 |
up |
서비스 실행: 컨테이너 생성 및 시작 (-d: 백그라운드) |
down |
서비스 중지: 컨테이너, 네트워크, 이미지 등을 일괄 삭제 |
ps |
현재 프로젝트 내 컨테이너들의 상태 확인 |
exec |
컨테이너 진입: 실행 중인 컨테이너 내부 셸 접속 |
4. 실무 활용 예제
🚀 [Scenario] Web-DB 스택 배포 및 업데이트
웹 서버(Nginx)와 데이터베이스(MySQL)를 함께 띄우고, 이미지를 최신화하여 재배포하는 과정입니다.
[Step 1: 최신 이미지 확보 및 배포]
# 1. 정의된 모든 서비스의 최신 이미지를 pull
$ docker compose pull
# 2. 변경된 이미지를 반영하여 컨테이너 재시작 (백그라운드)
$ docker compose up -d
$ docker compose pull
# 2. 변경된 이미지를 반영하여 컨테이너 재시작 (백그라운드)
$ docker compose up -d
[Step 2: 실행 상태 및 로그 확인]
[상태 확인]
$ docker compose ps
[실시간 로그]
$ docker compose logs -f
[Step 3: 컨테이너 내부 디버깅]
# web 서비스 컨테이너 안으로 접속하여 설정 파일 확인
$ docker compose exec web bash
$ docker compose exec web bash
⚠️ 주의 사항 (Caution)
- 데이터 영속성(Persistence): 컨테이너는 삭제 시 내부 데이터가 사라집니다. DB 데이터 등은 반드시
volumes를 통해 호스트 디렉토리에 연결해야 합니다. - 포트 중복: 호스트 OS에서 이미 사용 중인 포트를 매핑할 경우 충돌이 발생하므로 주의하십시오.
