Docker Compose 명령어 완벽 가이드: 다중 컨테이너 관리의 핵심

도커 컴포즈(Docker Compose)는 여러 컨테이너를 관리하는 데 유용한 도구입니다. 이 포스트에서는 도커 컴포즈를 사용하는 방법과 주요 커맨드를 설명하겠습니다.

---

도커 컴포즈 커맨드

도커 엔진을 실행할 때는 docker 명령어를 사용하지만, 도커 컴포즈는 docker-compose 명령어를 사용합니다. 현재 디렉토리에 도커 컴포즈 설정 파일(docker-compose.yml)이 존재하는 경우, -f 옵션은 생략할 수 있습니다.

주요 커맨드

• up: 컴포즈 정의 파일에 정의된 컨테이너, 네트워크, 볼륨을 생성하고 실행합니다
• down: 컴포즈 정의 파일에 정의된 컨테이너와 네트워크를 종료하고 삭제합니다
• stop: 실행 중인 컨테이너를 종료합니다

2025년 최신 명령어 형식

# 최신 Docker Compose V2 (권장)
docker compose up
docker compose down

# 기존 Docker Compose V1 (레거시)
docker-compose up
docker-compose down

---

도커 컴포즈 up 커맨드

도커 컴포즈의 up 커맨드는 다음과 같은 형식으로 사용됩니다:

docker-compose -f 정의파일경로 up [옵션]

up 커맨드 옵션

-d	백그라운드로 실행합니다
--no-color	출력 내용을 흑백으로 설정합니다
--no-deps	링크된 서비스를 실행하지 않습니다
--force-recreate	설정이나 이미지가 변경되지 않더라도 컨테이너를 재생성합니다
--no-build	이미지가 없어도 이미지를 빌드하지 않습니다
--build	컨테이너를 실행하기 전에 이미지를 빌드합니다
--abort-on-container-exit	하나의 컨테이너가 종료되면 모든 컨테이너를 종료합니다
-t, --timeout	컨테이너 종료 시 타임아웃을 설정합니다 (기본값: 10초)
--remove-orphans	컴포즈 파일에 정의되지 않은 서비스의 컨테이너를 삭제합니다
--scale	컨테이너의 수를 변경합니다

실무 활용 예시

# 백그라운드에서 서비스 시작
docker compose up -d

# 이미지 빌드 후 시작
docker compose up --build

# 강제 재생성하여 시작
docker compose up --force-recreate

# 특정 서비스만 시작
docker compose up web database

# 스케일링하여 시작
docker compose up --scale web=3 --scale worker=2

# 테스트 환경에서 실행 (하나 종료 시 모두 종료)
docker compose up --abort-on-container-exit

---

도커 컴포즈 down 커맨드

down 커맨드는 다음과 같이 사용됩니다:

docker-compose -f 정의파일경로 down [옵션]

down 커맨드 옵션

--rmi	삭제 시 이미지를 삭제합니다 (all: 모든 이미지 삭제, local: 커스텀 태그가 없는 이미지만 삭제)
-v, --volumes	볼륨을 삭제합니다 (external로 지정된 볼륨은 삭제하지 않음)
--remove-orphans	컴포즈 파일에 정의되지 않은 서비스의 컨테이너도 삭제합니다

실무 활용 예시

# 기본 종료 (컨테이너와 네트워크만 삭제)
docker compose down

# 볼륨까지 함께 삭제
docker compose down -v

# 이미지까지 모두 삭제
docker compose down --rmi all

# 로컬 이미지만 삭제
docker compose down --rmi local

# 고아 컨테이너까지 삭제
docker compose down --remove-orphans

---

도커 컴포즈 stop 커맨드

stop 커맨드는 다음과 같이 사용됩니다:

docker-compose -f 정의파일경로 stop

stop vs down 차이점

stop	중지	유지	유지	유지
down	삭제	삭제	유지	유지

# 컨테이너만 중지 (재시작 가능)
docker compose stop

# 특정 서비스만 중지
docker compose stop web

# 중지된 서비스 재시작
docker compose start

# 재시작
docker compose restart

---

도커 컴포즈 주요 커맨드

도커 컴포즈에서 자주 사용되는 커맨드는 다음과 같습니다:

커맨드	설명	예시
up	컨테이너를 생성하고 실행합니다	docker compose up -d
down	컨테이너와 네트워크를 종료하고 삭제합니다	docker compose down -v
stop	컨테이너를 종료합니다	docker compose stop
ps	실행 중인 컨테이너 목록을 출력합니다	docker compose ps
config	컴포즈 파일의 내용을 확인합니다	docker compose config
port	포트 설정 내용을 출력합니다	docker compose port web 80
logs	컨테이너의 로그를 출력합니다	docker compose logs -f web
start	중지된 컨테이너를 시작합니다	docker compose start
kill	컨테이너를 강제 종료합니다	docker compose kill
exec	실행 중인 컨테이너에서 명령어를 실행합니다	docker compose exec web bash
run	새로운 컨테이너를 실행합니다	docker compose run web npm test
create	컨테이너를 생성합니다	docker compose create
restart	컨테이너를 재시작합니다	docker compose restart web
pause	컨테이너를 일시 정지합니다	docker compose pause web
unpause	일시 정지된 컨테이너를 재개합니다	docker compose unpause web
rm	종료된 컨테이너를 삭제합니다	docker compose rm
build	이미지를 빌드합니다	docker compose build --no-cache
pull	이미지를 내려받습니다	docker compose pull
scale	컨테이너 수를 지정합니다	docker compose scale web=3
events	실시간 이벤트를 수신합니다	docker compose events
help	도움말을 출력합니다	docker compose help

---

도커 컴포즈 실행 예시

도커 컴포즈를 실행하는 방법은 다음과 같습니다:

도커 컴포즈 up 실행

docker compose up

위 명령을 실행하면 다음과 같은 출력이 나타납니다:

WARN[0000] /Users/yunsuhyeon/Downloads/docker/compose/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion 
[+] Running 3/0
 ✔ Network compose_wordpressnet001     Created                                                                                                   0.0s 
 ✔ Container compose-mysqlex001-1      Created                                                                                                   0.0s 
 ✔ Container compose-wordpressex001-1  Created                                                                                                   0.0s 
Attaching to mysqlex001-1, wordpressex001-1
mysqlex001-1      | 2025-02-03 05:52:54+00:00 [Note] [Entrypoint]: Entrypoint script for MySQL Server 8.4.4-1.el9 started.
wordpressex001-1  | AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.18.0.3. Set the 'ServerName' directive globally to suppress this message
mysqlex001-1      | 2025-02-03 05:52:54+00:00 [Note] [Entrypoint]: Switching to dedicated user 'mysql'
wordpressex001-1  | [Mon Feb 03 05:52:54.625893 2025] [mpm_prefork:notice] [pid 1:tid 1] AH00163: Apache/2.4.62 (Debian) PHP/8.2.27 configured -- resuming normal operations
mysqlex001-1      | 2025-02-03T05:52:55.080791Z 0 [System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections. Version: '8.4.4'  socket: '/var/run/mysqld/mysqld.sock'  port: 3306  MySQL Community Server - GPL.

위 출력은 MySQL과 워드프레스 컨테이너가 성공적으로 생성되었음을 나타냅니다.

도커 컴포즈 down 실행

docker compose down

이 명령을 실행하면 다음과 같은 출력이 나타납니다:

WARN[0000] /Users/yunsuhyeon/Downloads/docker/compose/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion 
[+] Running 3/0
 ✔ Container compose-wordpressex001-1  Removed                                                                                                   0.0s 
 ✔ Container compose-mysqlex001-1      Removed                                                                                                   0.0s 
 ✔ Network compose_wordpressnet001     Removed                                                                                                   0.0s 

위 출력은 정의된 모든 컨테이너와 네트워크가 성공적으로 삭제되었음을 나타냅니다.

---

도커 엔진에서 도커 컴포즈 컨테이너 명칭 다루기

도커 컴포즈로 실행된 컨테이너는 도커 엔진에서도 관리할 수 있습니다. 그러나 도커 컴포즈로 실행된 컨테이너는 임의의 명칭을 가지며, 보통 폴더이름_서비스명_번호 형식으로 생성됩니다. 예를 들어, docker-compose -f sample up 명령을 실행하면 folder_sample_1이라는 컨테이너명이 생성됩니다.

컨테이너 명명 규칙

# 기본 형식
프로젝트명_서비스명_번호

# 실제 예시
compose_web_1
compose_database_1
myproject_api_1
myproject_redis_1

컨테이너 이름 커스터마이징

version: "3.8"

services:
  web:
    image: nginx
    container_name: my-custom-web  # 커스텀 이름 지정

  database:
    image: mysql:8.0
    # container_name 미지정 시 자동 생성

스케일링 주의사항

--scale 옵션을 사용하면 같은 구성의 컨테이너를 여러 개 생성할 수 있지만, 포트 번호가 중복될 경우 실행되지 않으므로 주의해야 합니다.

# 포트 충돌 발생 예시 (잘못된 사용)
docker compose up --scale web=3  # 모든 web 컨테이너가 같은 포트 사용

# 올바른 스케일링 (포트 매핑 제거)
version: "3.8"
services:
  web:
    image: nginx
    # ports 섹션 제거하고 로드 밸런서 사용

  nginx-lb:
    image: nginx
    ports:
      - "80:80"
    # 로드 밸런서 설정

실무 관리 팁

# 프로젝트별 컨테이너 확인
docker compose ps

# 특정 프로젝트의 모든 컨테이너 확인
docker ps --filter "label=com.docker.compose.project=myproject"

# 컨테이너 로그 확인
docker compose logs web
docker compose logs -f --tail=100 database

# 컨테이너 내부 접근
docker compose exec web bash
docker compose exec database mysql -u root -p

# 리소스 사용량 모니터링
docker compose top
docker stats $(docker compose ps -q)

도커 컴포즈를 통해 효율적으로 컨테이너를 관리하고, 필요에 따라 명령어를 잘 활용할 수 있길 바랍니다.