Docker Compose v2 핵심 개념과 명령어 정리

Docker Compose는 여러 개의 컨테이너로 구성된 애플리케이션을 하나의 설정 파일(docker-compose.yml)로 정의하고, 실행·중지·관리할 수 있게 해주는 도구이다. 즉, 애플리케이션 전체 실행 환경을 코드로 정의하고 관리하는 도구라고 볼 수 있다.

Docker Compose 활용

단일 명령어(docker-compose up/down)로 서비스 전체의 생명주기를 제어할 수 있다는 점이 Compose의 가장 큰 장점이다. 단일 컨테이너 실행에 적합한 docker run과 달리, Compose는 서비스 간 의존성, 공용 네트워크, 볼륨 마운트, 환경 변수 등을 한 번에 관리하는 데 적합하다. Compose를 사용하면 다음과 같은 이점이 있다.

• 여러 컨테이너를 한 번의 명령어로 동시에 실행
• 서비스 간 네트워크가 자동으로 구성되어 서비스명으로 내부 DNS 통신 가능
• 개발/운영 환경을 동일한 설정 파일로 재현 가능
• 컨테이너, 네트워크, 볼륨의 생명주기를 명확하게 관리 가능

Docker Compose 서비스(Service)

Compose 설정에 정의되는 서비스에는 어떤 이미지를 사용할 것인가, 어떻게 컨테이너를 실행할 것인가, 어떤 설정(포트, 환경 변수, 볼륨 등)을 적용할 것인가 등의 설정이 추가된다. 즉, ‘컨테이너를 어떻게 만들 것인지에 대한 설계도’와 같다.

Docker Compose 프로젝트

Compose는 프로젝트명을 기준으로 리소스를 격리한다. 기본적으로 현재 디렉터리명을 프로젝트명으로 하며, -p 옵션으로도 프로젝트명을 지정할 수 있다.
예를 들어 web, db 서비스가 정의된 Compose 파일을 실행할 때 프로젝트 이름을 다르게 하면 완전히 다른 컨테이너, 네트워크, 볼륨이 된다. 그러므로 프로젝트를 이용하면 동일한 서버에서 여러 환경(프로젝트명: dev, staging, prod)을 동시에 운영할 수 있다.

컨테이너 격리

실행되는 컨테이너명은 <프로젝트명>_<서비스명>_<번호>의 형태로 만들어지고, 프로젝트명이 다르면 컨테이너명이 충돌하지 않는다.

네트워크 격리

특히, 프로젝트마다 기본 네트워크를 자동 생성한다. 네트워크명은 <프로젝트명>_default이다. 이 네트워크에는 같은 프로젝트의 컨테이너만 자동 연결되고 서비스명으로 내부 통신이 가능하지만, 기본설정에서는 다른 프로젝트 컨테이너와는 DNS와 통신은 자동으로 연결되지 않는다. 즉, 프로젝트가 다르면 네트워크는 분리된다.(수동으로는 연결가능)

볼륨 격리

자동 생성되는 볼륨도 프로젝트 단위로 분리되고, 볼륨명은 <프로젝트명>_<볼륨명>이다. 이를 통해 데이터 충돌을 방지하고 프로젝트명을 dev나 prod로 지정해 같은 환경 데이터 간의 분리도 가능하다.

Image는 프로젝트에 속하지 않음

build: 설정이 있을 경우 image: 설정이 생략되면 이미지명은 <프로젝트명>_<서비스명>이다. 하지만 이미지는 Docker 전체에서 공유되고 프로젝트 개념과는 무관하다.

version: "3.9"
 
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
 
  worker:
    build:
      context: ./worker
 

위처럼 image: 설정이 없으면 생성되는 이미지명은 <프로젝트명>_api, <프로젝트명>_worker이고, 설정이 있으면 그 이름으로 생성된다.

-p 옵션: 프로젝트명 지정

docker-compose 명령 실행 시 -p 옵션을 사용하면 프로젝트명을 임의로 지정할 수 있다.
다음과 같은 경우에는 -p 옵션 사용이 필요하다.

• 하나의 서버에서 여러 Compose 프로젝트를 동시에 운영하는 경우
• 개발, 테스트, 운영 환경을 동일한 설정 파일로 관리하는 경우
• CI/CD 파이프라인에서 자동 실행·정리 작업을 수행하는 경우
• 팀 단위 협업에서 컨테이너 이름 규칙을 통일하고 싶은 경우

docker compose up 과 docker compose up --build 차이

docker compose up

docker-compose up은 실행 가능한 이미지가 없고 build: 설정이 있으면 빌드를 한다. 하지만 기존 이미지가 있으면 빌드 없이 컨테이너를 실행한다.

아래와 같은 경우 이미지를 빌드하지 않고 이전 이미지를 사용하므로 주의한다.

• Dockerfile이 변경되었지만 이미지가 이미 존재하는 경우
• 전에 docker-compose build 또는 docker-compose up --build로 생성된 이미지가 있는 경우
• image가 지정되어 있고, 해당 이미지가 로컬에 이미 존재하는 경우

docker compose up --build

build: 설정이 있으면 컨테이너 실행 전에 이미지를 다시 빌드한다. Dockerfile이 수정되었거나, 이미지 빌드 단계에서 포함되는 파일이 변경 경우 재빌드가 필요하다. 최신 베이스 이미지를 가져오려면 --pull 옵션을 추가한다.

Docker Compose 주요 명령

Docker Compose v2부터는 Docker CLI에 통합되어, 별도의 바이너리가 아닌 docker compose 명령을 사용한다.

# 이미지빌드(dockerfile 기반)
docker compose build 
 
# 컨테이너 실행 (이미지 없으면 빌드, -d: 백그라운드 실행)
docker compose up -d 
 
# 이미지 재빌드 후 실행
docker compose up -d --build 
 
# 프로젝트명 지정
docker compose -p <프로젝트명> up 
 
# 서비스 상태 확인
docker compose ps 
docker compose ps -p <프로젝트명>
 
# 로그 확인
docker compose logs -f --tail=1000 
docker compose -p <프로젝트명> logs -f 
 
 
# 컨테이너 접속
docker compose exec <서비스명> /bin/bash 
docker compose -p <프로젝트명> exec <서비스명> /bin/bash 
 
# 서비스 중지 / 재시작
docker compose stop
docker compose start
docker compose restart
 
# 리소스 제거(볼륨 유지)
docker compose down 
docker compose -p <프로젝트명> down 
 
# 리소스 제거(볼륨 삭제)
docker compose down -v

명령어별 볼륨, 네트워크 상태

(끝)