Docker Compose 커맨드 사용법

Docker Compose는 여러 개의 컨테이너(container)로 구성된 애플리케이션을 관리하기 위한 간단한 오케스트레이션(Orchestration) 도구입니다. 이번 포스팅에서는 Compose 애플리케이션을 터미널에서 제어하기 위해 사용되는 Docker Compose 커맨드에 대해서 알아보겠습니다.

docker compose와 docker-compose

본격적으로 커맨드를 살펴보기 전에 짚고 넘어갈 부분이 있는데요. 예전에는 파이썬으로 만들어진 별도 실행 파일인 docker-compose(하이픈)를 설치해서 썼지만, 지금은 Docker CLI에 내장된 플러그인 형태의 docker compose(공백)가 표준입니다. 전자를 Compose V1, 후자를 Compose V2라고 부르는데, V1은 2023년에 지원이 종료되어 더 이상 업데이트되지 않습니다.

그래서 이 글의 모든 예제는 V2 기준인 docker compose로 작성했습니다. 혹시 아직 docker-compose 커맨드에 익숙하시더라도 하이픈을 공백으로 바꾸기만 하면 사용법은 거의 동일하니 걱정하지 않으셔도 됩니다. 설치된 버전은 다음과 같이 확인할 수 있습니다.

$ docker compose version
Docker Compose version v2.38.2

-f 옵션

Docker Compose는 기본적으로 커맨드를 실행하는 디렉터리에 있는 compose.yaml을 설정 파일로 사용합니다. 예전 관행인 docker-compose.yml이나 docker-compose.yaml도 여전히 인식하지만, V2부터는 compose.yaml이 권장되는 파일명입니다. 다른 이름이나 경로의 파일을 설정 파일로 사용하고 싶다면 -f 옵션으로 명시를 해줍니다.

$ docker compose -f compose-local.yaml up

-f 옵션은 여러 개의 설정 파일을 사용할 때도 사용할 수 있습니다. 이때는 나중에 나오는 설정이 앞에 나오는 설정보다 우선하게 됩니다.

$ docker compose -f compose.yaml -f compose-test.yaml up

up

docker-compose up 커맨드는 아마도 Docker Compose에서 가장 자주 사용되는 커맨드일 텐데요. Docker Compose에 정의되어 있는 모든 서비스 컨테이너를 한 번에 생성하고 실행하기 위해서 사용합니다.

보통 -d 옵션을 사용하여 백그라운드에서 컨테이너를 띄우는 경우가 많습니다.

$ docker compose up -d
 Network django-app_default  Created
 Container django-app-db-1  Started
 Container django-app-web-1  Started

-d 옵션을 사용하지 않으면 현재 터미널에 컨테이너의 로그가 출력되고 Ctrl + C를 눌러서 탈출하는 순간 컨테이너가 모두 정지되기 때문입니다.

down

docker compose down 커맨드는 docker compose up 커맨드와 정반대의 동작을 합니다. Docker Compose에 정의되어 있는 모든 서비스 컨테이너를 한 번에 정지시키고 삭제합니다.

$ docker compose down
 Container django-app-web-1  Stopped
 Container django-app-db-1  Stopped
 Container django-app-web-1  Removed
 Container django-app-db-1  Removed
 Network django-app_default  Removed

start

docker compose start 커맨드는 내려가 있는 특정 서비스 컨테이너를 올리기 위해서 사용합니다. 대부분의 경우에는 docker compose up 커맨드를 사용해도 내려간 서비스를 알아서 올려주므로 무방합니다.

$ docker compose start web
 Container django-app-web-1  Started

stop

docker compose stop 커맨드는 docker compose start 커맨드와 정반대의 동작을 합니다. 돌아가고 있는 특정 서비스 컨테이너를 정지시키기 위해서 사용합니다.

$ docker compose stop web
 Container django-app-web-1  Stopped

ps

docker compose ps 커맨드는 Docker Compose에 정의되어 있는 모든 서비스 컨테이너 목록을 조회할 때 사용합니다.

$ docker compose ps
NAME               IMAGE              COMMAND                  SERVICE   STATUS         PORTS
django-app-db-1    postgres           "docker-entrypoint.s…"   db        Up 2 minutes   5432/tcp
django-app-web-1   python:3.13-slim   "python -m http.serv…"   web       Up 2 minutes   0.0.0.0:8000->8000/tcp

V1 시절에는 Name, Command, State, Ports 정도만 보여줬는데, V2에서는 IMAGE와 SERVICE 컬럼이 추가되어 어떤 이미지로 어떤 서비스가 떠 있는지 한눈에 파악하기 좋아졌습니다.

logs

docker compose logs 커맨드는 서비스 컨테이너의 로그를 확인하고 싶을 때 사용하며, 보통 -f 옵션을 붙여서 실시간 로그를 확인합니다.

$ docker compose logs -f web
web-1  | Watching for file changes with StatReloader
web-1  | Performing system checks...
web-1  |
web-1  | System check identified no issues (0 silenced).
web-1  |
web-1  | Django version 5.2, using settings 'our_project.settings'
web-1  | Starting development server at http://0:8000/
web-1  | Quit the server with CONTROL-C.

exec

docker compose exec 커맨드는 실행 중인 서비스 컨테이너를 대상으로 어떤 명령어를 날릴 때 사용합니다.

$ docker compose exec db psql -U postgres
psql (18.4 (Debian 18.4-1.pgdg13+1))
Type "help" for help.

postgres=#

run

docker compose run 커맨드는 서비스 컨테이너의 특정 명령어를 일회성으로 실행할 때 사용합니다.

$ docker compose run --rm web env
PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=2d80ca4d1f57
GPG_KEY=7169605F62C751356D054A26A821E680E5FA6305
PYTHON_VERSION=3.13.14
HOME=/root

일회성 실행이라 작업이 끝난 뒤 컨테이너가 남지 않도록 --rm 옵션을 붙여주는 것이 좋습니다.

config

docker compose config 커맨드는 Docker Compose 설정을 확인할 때 사용합니다. -f 옵션으로 여러 개의 설정 파일을 사용할 때, 최종적으로 어떻게 설정이 적용되는지 확인해볼 때 유용합니다.

$ docker compose config
name: django-app
services:
  db:
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
    image: postgres
    networks:
      default: null
  web:
    command:
      - python
      - manage.py
      - runserver
      - "0:8000"
    depends_on:
      db:
        condition: service_started
        required: true
    image: python:3.13-slim
    networks:
      default: null
    ports:
      - mode: ingress
        target: 8000
        published: "8000"
        protocol: tcp
networks:
  default:
    name: django-app_default

V1에서는 맨 아래에 version: '3.0' 같은 버전 필드가 붙었는데, V2에서는 이 필드가 없어지고 대신 프로젝트 이름(name)과 네트워크 설정이 명시적으로 채워집니다.

마치며

이상으로 자주 사용되는 Docker Compose 커맨드 위주로 간단하게 어떻게 사용하는지 살펴보았습니다. 예전 docker-compose(V1) 대신 이제는 docker compose(V2)가 표준이라는 점만 기억하시면, 나머지 커맨드는 이름 그대로 직관적으로 사용하실 수 있습니다.

Docker Compose의 다른 커맨드는 Docker Compose 공식 레퍼런스를 참고 바랍니다.