초보자도 따라하는 Docker Compose 명령어 치트시트: 자주 쓰는 커맨드 모음 🚀

G: 안녕하세요, 개발자 여러분! 복잡한 마이크로서비스 아키텍처를 관리하거나, 여러 서비스가 유기적으로 연결된 애플리케이션을 개발할 때마다 머리가 지끈거린 경험 있으신가요? 🤯 각 서비스마다 컨테이너를 일일이 만들고, 네트워크를 설정하고, 볼륨을 연결하는 작업은 생각만 해도 아찔합니다.

이런 고통을 덜어주기 위해 등장한 것이 바로 Docker Compose입니다! 🎩 Docker Compose는 YAML 파일을 통해 여러 Docker 컨테이너를 한 번에 정의하고 실행할 수 있도록 도와주는 마법 지팡이와 같습니다. 오늘은 이 마법 지팡이를 처음 잡아보는 초보자분들도 쉽게 따라 할 수 있도록, 가장 자주 쓰이는 Docker Compose 명령어들을 모아 치트시트를 준비했습니다. 이제 복잡한 설정은 잊고, 핵심 명령어들로 개발 생산성을 확 끌어올려 보세요! 💪

📚 목차

1. Docker Compose, 왜 필요할까요?
2. 시작하기 전에: 준비물 확인 🛠️
3. 핵심 개념 잠깐 짚고 가기: docker-compose.yml 파일 이해하기
4. 자주 쓰는 Docker Compose 명령어 치트시트
   • 4.1. 서비스 라이프사이클 관리: 시작, 중지, 재시작 🔄
   • 4.2. 컨테이너 상태 확인 및 로그 보기 🔍
   • 4.3. 컨테이너 내부 명령어 실행 및 빌드 🧑‍💻
   • 4.4. 컨테이너 및 이미지 정리 🧹
   • 4.5. 유용한 보조 명령어 ℹ️
5. Docker Compose Pro 팁! ✨
6. 마무리하며: 이제 직접 해볼 시간! 🌟

1. Docker Compose, 왜 필요할까요?

여러분이 웹 서비스와 데이터베이스, 캐시 서버 등 다양한 구성 요소로 이루어진 애플리케이션을 개발한다고 상상해 보세요. 각각의 요소를 Docker 컨테이너로 만든다고 가정했을 때, 다음과 같은 문제에 직면할 수 있습니다.

• 수동 설정의 번거로움: docker run, docker network create, docker volume create 등 여러 명령어를 일일이 입력해야 합니다.
• 의존성 관리의 어려움: 데이터베이스가 웹 서버보다 먼저 시작되어야 하는 등의 의존성 문제를 수동으로 해결해야 합니다.
• 환경 일관성 부족: 개발 환경과 프로덕션 환경에서 컨테이너 설정이 달라질 경우 예측 불가능한 버그가 발생할 수 있습니다.

Docker Compose는 이런 문제들을 단 하나의 docker-compose.yml 파일로 해결해 줍니다. 이 파일에 서비스, 네트워크, 볼륨 등을 정의해두면, 단 한 줄의 명령어로 전체 애플리케이션 스택을 한 번에 올리고 내릴 수 있습니다. 마치 오케스트라의 지휘자처럼 말이죠! 🎼

2. 시작하기 전에: 준비물 확인 🛠️

이 치트시트를 따라하기 위해서는 두 가지가 준비되어 있어야 합니다.

1. Docker Desktop 설치: Windows, macOS, Linux 환경에 맞는 Docker Desktop을 설치해 주세요. Docker 엔진과 Docker Compose가 함께 설치됩니다.
   • Docker Desktop 다운로드
2. 터미널(Terminal) 또는 명령 프롬프트(CMD/PowerShell): 명령어를 입력할 수 있는 환경이 필요합니다.

설치가 완료되었다면 터미널에서 다음 명령어를 입력하여 Docker와 Docker Compose가 잘 설치되었는지 확인해 보세요.

docker --version
docker compose version

위 명령어를 입력했을 때 버전 정보가 출력되면 준비 완료입니다! ✅ (최신 Docker 버전에서는 docker-compose 대신 docker compose 형태로 사용합니다. 이 가이드에서는 최신 문법인 docker compose를 사용합니다.)

3. 핵심 개념 잠깐 짚고 가기: docker-compose.yml 파일 이해하기

Docker Compose의 모든 것은 docker-compose.yml 파일에서 시작됩니다. 이 YAML 파일은 애플리케이션을 구성하는 서비스들(컨테이너), 이들이 사용할 네트워크, 그리고 데이터 지속성을 위한 볼륨 등을 정의합니다.

가장 기본적인 docker-compose.yml 파일의 구조는 다음과 같습니다:

version: '3.8' # Docker Compose 파일 형식 버전 (최신 버전을 사용하는 것이 좋습니다)

services: # 애플리케이션을 구성하는 서비스들 (각 서비스는 하나의 컨테이너)
  web: # 'web' 서비스 정의
    build: . # 현재 디렉토리의 Dockerfile을 사용하여 이미지 빌드
    ports: # 호스트와 컨테이너 포트 매핑
      - "80:80"
    volumes: # 볼륨 마운트 (호스트:컨테이너)
      - .:/app
    depends_on: # 이 서비스가 시작되기 전에 'db' 서비스가 먼저 시작되어야 함
      - db

  db: # 'db' 서비스 정의
    image: postgres:13 # Docker Hub에서 'postgres:13' 이미지를 사용
    environment: # 환경 변수 설정
      POSTGRES_DB: mydatabase
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
    volumes: # 데이터 지속성을 위한 명명된 볼륨
      - db_data:/var/lib/postgresql/data

volumes: # 명명된 볼륨 정의
  db_data:

• version: Docker Compose 파일 포맷 버전을 나타냅니다. 최신 버전을 사용하는 것이 기능적으로 좋습니다.
• services: 애플리케이션을 구성하는 컨테이너들을 정의하는 핵심 섹션입니다. 각 서비스는 독립적인 컨테이너로 작동합니다.
• volumes: 컨테이너의 데이터를 영구적으로 저장하기 위한 볼륨을 정의합니다. db_data처럼 이름을 지정하면 호스트 머신에 영구적으로 저장됩니다.
• networks: 서비스 간의 통신을 위한 네트워크를 정의합니다. (명시하지 않으면 기본 브릿지 네트워크가 생성됩니다.)

이 파일을 프로젝트 루트 디렉토리에 생성한 후, 이제 본격적으로 명령어를 사용해볼 시간입니다! 🚀

4. 자주 쓰는 Docker Compose 명령어 치트시트

이제 실제로 프로젝트에서 가장 많이 사용될 명령어들을 하나씩 살펴보겠습니다. 각 명령어마다 설명, 사용 예시, 그리고 팁을 함께 제공합니다.

4.1. 서비스 라이프사이클 관리: 시작, 중지, 재시작 🔄

이 명령어들은 Docker Compose 프로젝트의 생명주기를 제어하는 데 사용됩니다.

• docker compose up ✨

  • 설명: docker-compose.yml 파일에 정의된 모든 서비스를 빌드(필요시), 생성하고 시작합니다. 이 명령어 하나로 전체 애플리케이션 스택을 배포할 수 있습니다.
  • 주요 옵션:
    • -d (detached mode): 백그라운드에서 서비스를 실행하고 터미널을 반환합니다. 가장 많이 사용되는 옵션입니다.
    • --build: 이미지 캐시를 사용하지 않고 항상 이미지를 다시 빌드합니다. Dockerfile을 수정했을 때 유용합니다.
    • --force-recreate: 서비스가 이미 실행 중이더라도 컨테이너를 강제로 다시 생성합니다.
  • 예시:

    docker compose up           # 포그라운드에서 모든 서비스 시작
    docker compose up -d        # 백그라운드에서 모든 서비스 시작 (가장 흔하게 사용)
    docker compose up -d --build # 백그라운드에서 시작하며 이미지 강제 재빌드
    docker compose up web       # 'web' 서비스만 시작 (단, 'web'이 의존하는 서비스도 함께 시작됨)

  • 💡 팁: -d 옵션 없이 up을 실행하면, 컨테이너의 로그가 터미널에 실시간으로 출력되어 개발 중 디버깅에 매우 유용합니다. 종료하려면 Ctrl+C를 누르세요.

• docker compose down 🧹

  • 설명: docker compose up으로 시작된 모든 서비스의 컨테이너를 중지하고 제거합니다. 정의된 네트워크도 함께 제거됩니다.
  • 주요 옵션:
    • --volumes (또는 -v): Docker Compose 파일에 정의된 명명된 볼륨(named volumes)도 함께 제거합니다. 데이터베이스 데이터 등을 완전히 초기화하고 싶을 때 사용합니다.
    • --rmi all: 서비스가 사용하는 모든 이미지를 제거합니다.
  • 예시:

    docker compose down         # 모든 서비스 컨테이너 중지 및 제거
    docker compose down --volumes # 컨테이너와 함께 명명된 볼륨도 제거

  • 💡 팁: 개발 환경을 완전히 초기화하고 싶을 때 docker compose down --volumes를 사용하면 깔끔하게 정리할 수 있습니다.

• docker compose start ▶️

  • 설명: 이전에 docker compose stop으로 중지되었지만 제거되지 않은 서비스 컨테이너들을 다시 시작합니다. 이미지를 다시 빌드하거나 컨테이너를 재생성하지 않습니다.
  • 예시:

    docker compose start        # 중지된 모든 서비스 재시작
    docker compose start web db # 'web'과 'db' 서비스만 재시작

• docker compose stop ⏸️

  • 설명: 현재 실행 중인 모든 서비스 컨테이너를 중지합니다. down과 달리 컨테이너는 제거되지 않고 Stopped 상태로 유지됩니다. 나중에 start 명령어로 빠르게 재시작할 수 있습니다.
  • 예시:

    docker compose stop         # 모든 서비스 중지
    docker compose stop web     # 'web' 서비스만 중지

• docker compose restart 🔄

  • 설명: 실행 중인 서비스 컨테이너를 중지한 후 다시 시작합니다. 컨테이너를 다시 생성하지 않고 재시작하는 편리한 명령어입니다.
  • 예시:

    docker compose restart      # 모든 서비스 재시작
    docker compose restart web  # 'web' 서비스만 재시작

4.2. 컨테이너 상태 확인 및 로그 보기 🔍

현재 실행 중인 서비스들의 상태를 확인하거나, 발생한 문제를 파악하기 위해 로그를 확인하는 데 사용됩니다.

• docker compose ps 🔍

  • 설명: 현재 프로젝트에 속한 서비스 컨테이너들의 상태를 보여줍니다. 이름, 명령어, 상태(Up/Exited), 포트 매핑 등을 한눈에 확인할 수 있습니다.
  • 예시:

    docker compose ps

  • 출력 예시:

          Name                     Command               State          Ports
    --------------------------------------------------------------------------------
    myproject-db-1      docker-entrypoint.sh postgres   Up      5432/tcp
    myproject-web-1     /bin/sh -c python app.py        Up      0.0.0.0:80->80/tcp

• docker compose logs 📜

  • 설명: 서비스 컨테이너에서 발생하는 로그를 출력합니다. 특정 서비스의 로그를 보거나, 실시간으로 로그를 추적할 때 유용합니다.
  • 주요 옵션:
    • -f (follow): 실시간으로 새로운 로그를 계속해서 출력합니다. 개발 중 디버깅에 필수!
    • --tail N: 마지막 N줄의 로그만 출력합니다.
    • --no-log-prefix: 로그 앞에 붙는 컨테이너 이름을 제거합니다.
  • 예시:

    docker compose logs           # 모든 서비스의 로그 출력
    docker compose logs web       # 'web' 서비스의 로그만 출력
    docker compose logs -f web    # 'web' 서비스의 로그를 실시간으로 추적 (Ctrl+C로 종료)
    docker compose logs --tail 10 db # 'db' 서비스의 마지막 10줄 로그 출력

  • 💡 팁: 여러 서비스의 로그를 한 번에 볼 때 docker compose logs -f를 사용하면, 각 서비스의 로그가 구별되어 출력되기 때문에 전체적인 흐름을 파악하기 좋습니다.

• docker compose config ⚙️

  • 설명: docker-compose.yml 파일을 파싱하여 최종적으로 적용될 설정을 출력합니다. YAML 파일 문법 오류나 설정 문제를 디버깅할 때 유용합니다.
  • 주요 옵션:
    • -q (quiet): 유효성 검사만 수행하고 결과는 출력하지 않습니다. 오류가 있을 때만 메시지를 출력합니다.
    • --services: 서비스 이름만 출력합니다.
    • --volumes: 볼륨 이름만 출력합니다.
  • 예시:

    docker compose config         # 파싱된 최종 설정 출력
    docker compose config -q      # 설정 파일 유효성만 검사

  • 💡 팁: YAML 파일에 오타가 있거나 잘못된 들여쓰기가 있을 경우 이 명령어로 쉽게 찾아낼 수 있습니다.

4.3. 컨테이너 내부 명령어 실행 및 빌드 🧑‍💻

개발 과정에서 컨테이너 내부로 들어가 작업하거나, 이미지 빌드를 직접 제어할 때 사용됩니다.

• docker compose exec 🧑‍💻

  • 설명: 실행 중인 특정 서비스 컨테이너 내에서 명령어를 실행합니다. 컨테이너의 쉘에 접속하거나, 특정 스크립트를 실행할 때 매우 유용합니다.
  • 주요 옵션:
    • -it: 대화형(interactive) 모드로 터미널을 할당합니다. 쉘에 접속할 때 필수입니다.
  • 예시:

    docker compose exec web bash    # 'web' 서비스 컨테이너의 bash 쉘에 접속 (가장 흔하게 사용)
    docker compose exec db psql -U myuser mydatabase # 'db' 컨테이너에서 PostgreSQL 클라이언트 실행
    docker compose exec web python manage.py makemigrations # Django 마이그레이션 실행

  • 💡 팁: 대부분의 컨테이너는 bash 쉘을 제공하지만, 일부 경량 컨테이너는 sh 쉘만 제공할 수 있습니다. bash가 안 되면 sh를 시도해 보세요!

• docker compose build 🏗️

  • 설명: docker-compose.yml 파일에 build 지시어가 있는 서비스의 이미지를 빌드합니다. docker compose up 시 자동으로 빌드되지만, 특정 이미지만 미리 빌드하거나 캐시를 무시하고 싶을 때 사용합니다.
  • 주요 옵션:
    • --no-cache: 빌드 시 이미지 캐시를 사용하지 않고 처음부터 다시 빌드합니다. Dockerfile을 수정했을 때 캐시 문제로 변경 사항이 반영되지 않을 때 유용합니다.
    • --pull: 빌드 시 필요한 베이스 이미지를 항상 Docker Hub에서 최신 버전으로 풀(pull)해옵니다.
  • 예시:

    docker compose build          # 모든 서비스의 이미지 빌드
    docker compose build web      # 'web' 서비스의 이미지만 빌드
    docker compose build --no-cache web # 'web' 이미지 캐시 무시하고 재빌드

  • 💡 팁: Dockerfile을 수정했는데 변경 사항이 적용되지 않는 것 같다면, --no-cache 옵션으로 다시 빌드해 보세요.

• docker compose pull ⬇️

  • 설명: docker-compose.yml 파일에 image 지시어가 있는 서비스의 이미지를 Docker Hub와 같은 레지스트리에서 미리 다운로드합니다. up 명령 시 자동으로 풀 되지만, 미리 다운로드하여 시작 시간을 단축할 수 있습니다.
  • 예시:

    docker compose pull           # 모든 서비스 이미지 다운로드
    docker compose pull db        # 'db' 서비스 이미지 다운로드

4.4. 컨테이너 및 이미지 정리 🧹

불필요한 컨테이너나 이미지를 제거하여 시스템 자원을 확보할 때 사용합니다.

• docker compose rm 🗑️

  • 설명: docker compose stop 등으로 중지된 서비스 컨테이너를 제거합니다. down 명령어와 달리 네트워크나 볼륨은 제거하지 않습니다.
  • 주요 옵션:
    • -f (force): 실행 중인 컨테이너도 강제로 제거합니다.
    • -s (stop): 제거하기 전에 컨테이너를 중지합니다.
  • 예시:

    docker compose rm             # 중지된 모든 서비스 컨테이너 제거 (확인 메시지 출력)
    docker compose rm -f web      # 'web' 서비스 컨테이너를 강제로 제거

  • 💡 팁: docker compose down이 더 포괄적인 정리 명령어이므로, 일반적으로 rm보다는 down을 더 많이 사용합니다.

4.5. 유용한 보조 명령어 ℹ️

• docker compose version ℹ️

  • 설명: 현재 설치된 Docker Compose의 버전을 확인합니다.
  • 예시:

    docker compose version

• `docker compose –file

  ` (또는 `-f`) 📂 * **설명:** 기본 `docker-compose.yml` 파일 대신 다른 이름의 Compose 파일을 사용하고 싶을 때 사용합니다. 예를 들어, 개발용(`docker-compose.dev.yml`)과 프로덕션용(`docker-compose.prod.yml`) 설정을 분리할 때 유용합니다. * **예시:** “`bash docker compose -f docker-compose.prod.yml up -d # 프로덕션용 설정 파일로 서비스 시작 docker compose -f docker-compose.yml -f docker-compose.override.yml up # 여러 파일 조합 “` * **💡 팁:** 여러 Compose 파일을 함께 사용하는 것은 매우 흔한 패턴입니다. 기본 설정에 추가적인 오버라이드 설정을 더할 때 유용합니다.

• `docker compose –project-name

  ` (또는 `-p`) 🏷️ * **설명:** Docker Compose 프로젝트의 이름을 설정합니다. 기본적으로 프로젝트가 위치한 디렉토리 이름이 프로젝트 이름으로 사용됩니다. 여러 개의 독립적인 Compose 프로젝트를 동시에 실행할 때 컨테이너 이름 충돌을 피하기 위해 사용합니다. * **예시:** “`bash docker compose -p my_awesome_app up -d # 프로젝트 이름을 ‘my_awesome_app’으로 설정 “` * **💡 팁:** 프로젝트 이름은 컨테이너 이름(예: `my_awesome_app-web-1`), 네트워크 이름 등에 접두사로 사용되어 식별을 용이하게 합니다.

5. Docker Compose Pro 팁! ✨

초보자 단계를 넘어, Docker Compose를 좀 더 효과적으로 사용하기 위한 몇 가지 팁입니다.

• 항상 프로젝트 루트 디렉토리에서 명령어 실행: docker-compose.yml 파일이 있는 디렉토리에서 명령어를 실행해야 합니다. 그렇지 않으면 “Can’t find a suitable configuration file”과 같은 오류가 발생할 수 있습니다. 🚨
• .env 파일 활용: 민감한 정보(예: 데이터베이스 비밀번호)나 환경에 따라 달라지는 값들은 docker-compose.yml 파일에 직접 넣는 대신, .env 파일에 정의하여 관리하는 것이 좋습니다. Compose는 자동으로 .env 파일을 로드합니다.
  • ./.env 예시:

    DB_PASSWORD=my_secure_password
    APP_PORT=8080

  • docker-compose.yml에서 사용:

    services:
      db:
        image: postgres
        environment:
          POSTGRES_PASSWORD: ${DB_PASSWORD}
      web:
        ports:
          - "${APP_PORT}:80"

• docker compose up -d 후 docker compose logs -f: 서비스를 백그라운드로 올린 후, 바로 로그를 확인하여 서비스가 정상적으로 시작되었는지, 오류는 없는지 확인하는 습관을 들이는 것이 좋습니다.
• .dockerignore 파일 사용: Dockerfile을 사용할 때 빌드 컨텍스트에 포함되지 않아야 할 파일들(예: node_modules, .git, .env)을 .dockerignore에 명시하여 빌드 시간을 단축하고 이미지 크기를 줄일 수 있습니다.
• 볼륨 마운트 시 권한 문제 주의: 호스트 디렉토리를 컨테이너에 마운트할 때, 컨테이너 내부의 프로세스 사용자와 호스트의 파일 소유자/권한이 맞지 않아 문제가 발생하는 경우가 있습니다. 이 경우 Dockerfile에서 컨테이너 내부의 사용자(USER)를 조정하거나, 호스트 디렉토리의 권한을 변경해 보세요.

6. 마무리하며: 이제 직접 해볼 시간! 🌟

지금까지 Docker Compose의 핵심 명령어들을 자세히 살펴보았습니다. 처음에는 생소하고 복잡해 보일 수 있지만, 몇 번 직접 사용해보고 익숙해지면 여러분의 개발 워크플로우에 엄청난 효율성을 가져다줄 것입니다. 🚀

이 치트시트는 여러분이 Docker Compose를 활용하여 복잡한 다중 컨테이너 애플리케이션을 쉽게 관리하고, 개발 환경을 표준화하는 데 큰 도움이 될 것입니다. 이제 이론을 넘어 직접 프로젝트에 적용해 보세요. 작은 예제부터 시작하여 점진적으로 익숙해지는 것이 중요합니다.

궁금한 점이 있다면 언제든지 Docker 공식 문서나 커뮤니티의 도움을 받을 수 있습니다! Docker Compose 공식 문서

꾸준한 연습과 탐구를 통해 Docker Compose 마스터가 되시기를 응원합니다! Happy Dockering! 🐳✨