[Docker] Docker Compose

Bam·2025년 6월 21일
dockerdocker compose도커도커 컴포즈

Docker

목록 보기
7/7
post-thumbnail

Docker Compose

도커 컴포즈 Docker Compose는 여러 컨테이너로 구성된 애플리케이션을 쉽게 정의하고 한 번에 실행할 수 있도록 도와주는 도구입니다.

웹 애플리케이션 같은 경우 크게 프론트엔드 서비스 + 백엔드 서비스 + 데이터베이스 등 최소 세 개의 컨테이너가 동작하기 때문에 이들을 구성 및 활용할 때마다 일일이 Docker 명령들로 조작하기에는 비효율적인 작업들을 거치게 됩니다.

그래서 이런 작업들을 하나의 설정 파일에 정의해놓고 명령어 하나를 통해 시스템 시작부터 종료까지 제어할 수 있도록 만들어주는 것이 도커 컴포즈라는 도구입니다.

Docker Desktop 앱을 설치한 경우, 해당 앱에 도커 컴포즈가 포함되어 있습니다. 리눅스 환경에서는 따로 설치를 해야합니다.

docker-compose.yml

도커 컴포즈를 사용하기 위해서 docker-compose.yml라는 파일에 서비스 관련 명령어들을 정의합니다.

파일 이름은 반드시 docker-compose.yml이라고 짓습니다. -f 옵션을 사용해서 파일 이름을 지정하는 방법이 있긴하지만 웬만해서는 docker-compose.yml이라고 짓습니다. (밑에서 설명)

docker-compose.yml에 애플리케이션을 구성하는데 필요한 모든 컨테이너(프론트, 백, DB 등)를 정의하게 됩니다. 이 정의에 따라서 도커 컴포즈가 .yml에 정의된 내용을 해석하여 도커 엔진이 동작하도록 만들어줍니다.

다음은 제가 어떤 프로젝트를 진행하면서 사용했었던 .yml 파일을 조금 추린 내용입니다. 아마 이 포스트가 끝날 때 즈음이면 이 설정 파일이 무슨 의미를 가지고 있는지 이해할 수 있을 것 입니다.

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: mysql
    restart: always
    ports:
      - "${MYSQL_PORT}:3306"
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql

  backend:
    build: ./backend
    container_name: backend
    restart: always
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      SPRING_DATASOURCE_URL: ${SPRING_DATASOURCE_URL}
      SPRING_DATASOURCE_USERNAME: ${SPRING_DATASOURCE_USERNAME}
      SPRING_DATASOURCE_PASSWORD: ${SPRING_DATASOURCE_PASSWORD}
      SPRING_PROFILES_ACTIVE: dev
    ports:
      - ${SPRING_APP_PORT}:8080

  frontend:
    build: ./frontend
    container_name: frontend
    restart: always
    depends_on:
      - backend
    ports:
      - "8080:8080"

volumes:
  mysql_data:

docker-compse.yml 작성하기

우선 .yml 포맷의 경우 들여쓰기(공백 두 번)를 통해 각 항목을 구분합니다. 그래서 설정 파일을 작성할 때는 들여쓰기, 공백 등에 유의해주세요.

주석은 #을 사용합니다.

주 항목

토대가 되는 항목으로 version, services, volumes, networks가 있습니다. 주 항목을 적고 해당 항목들 밑에 세부 설정을 넣습니다.

  • version: Docker-compose의 버전을 명시합니다. 작성 시점 기준(2025-06-21)으로 3.8을 주로 사용합니다.
  • services: 서비스, 즉 컨테이너들을 정의합니다.
  • volumes: 사용할 볼륨을 정의합니다.
  • networks: 사용자 정의 네트워크를 정의합니다.

configs, secrets라는 주 항목도 있는데 각 설정 파일 지정이나 보안 데이터 지정에 사용합니다. 입문 수준에서는 위 네 개 정도만 알아도 충분합니다.

자주 사용되는 항목

전체적인 속성 항목은 공식 문서에서 확인하실 수 있습니다.

설정에 사용되는 속성 항목들이 엄청 많기 때문에 여기서는 자주 사용되는 항목들에 대해서만 소개하고 넘어가려고 합니다.

services 하위에서 자주 사용되는 항목

항목설명
image사용할 Docker 이미지 지정
buildDockerfile을 직접 빌드할 때 사용
container_name컨테이너 이름 설정
ports호스트와 컨테이너 간 포트 바인딩
volumes볼륨 또는 디렉터리 마운트 설정
environment환경변수 설정
env_file.env 파일 불러오기
depends_on의존 서비스 설정 (실행 순서 조정)
command컨테이너 실행 시 명령 덮어쓰기
restart컨테이너 재시작 정책 설정
networks연결할 네트워크 지정
healthcheck컨테이너 상태 확인용 설정
extra_hosts/etc/hosts에 추가할 항목 설정

container_name은 컨테이너 이름을 명시하는 항목인데요. 이는 도커 내부에서 실제 컨테이너 이름으로 사용되는 컨테이너 이름을 지정하는 항목입니다.

서비스 이름이라는 개념이 아래에서 등장하는데 서비스 이름은 도커 컴포즈 services 항목에서 각 컨테이너를 구분하기 위한 논리적 이름으로 container_name과는 다른 개념임에 유의해주세요.

주 항목의 volumes와 services 하위의 volumes는 같은 항목명을 가지고 있지만 서로 역할이 다릅니다.

  • 주 항목 volumes: 필요한 볼륨을 정의. 실제 볼륨을 생성 또는 재사용
  • services 하위 volumes: 해당 컨테이너에서 볼륨 마운트

추가적으로 logging이라는 항목도 자주 사용됩니다. 각 컨테이너의 로그 설정을 제어하는 데 사용됩니다.

항목설명
driver사용할 로그 드라이버 종류
default로 json-file을 사용
options로그 드라이버 별 커스텀 옵션을 지정

volumes 하위에서 자주 사용되는 항목

항목설명
[볼륨이름]볼륨 정의 (보통은 {}만 작성)
driver볼륨 드라이버 설정
external외부에서 생성한 볼륨 사용 여부 지정

networks 하위에서 자주 사용되는 항목

항목설명
[네트워크이름]네트워크 정의
driver네트워크 드라이버 설정
external외부 네트워크 사용 여부 지정

작성법

몇 가지 권장되는 작성 사항들이 있으며 다음과 같습니다.

  • 첫 줄에 version 정의
  • 이후 주 항목들(services, volumes, networks)를 정의하고 하위에 세부 설정 정의
  • 항목 간 관계는 들여쓰기를 통해 표현
  • 이름 뒤에 : 명시, : 뒤에 반드시 공백 포함
  • 컨테이너, 볼륨, 네트워크 이름은 주 항목 바로 아래 한 번 들여쓰기 하고 작성
  • 하위 세부 설정은 이름 아래 한 번 들여쓰기 하고 작성
  • 같은 레벨에서 줄바꿈 발생 시 앞에 -를 적고 설정 항목 작성
  • 문자열은 ' 또는 " 사용

위 작성법에 따라 docker-compose.yml을 예시로 작성해보면 다음과 같습니다.

version: 3.8

services:
  db:	#서비스 이름
    image: mysql:8.0
    volumes: mysql_data:/var/lib/mysql
    ports: "3306"
  
  frontend: 
    depends_on: backend
    
  backend:
    depends_on: frontend
    ports:
      - "8080"	#항목의 줄바꿈이나 여러 속성은 하이픈 -을 사용하고 정의

volumes:
  mysql_data:

Docker Compose 명령어

그러면 작성한 설정 파일을 토대로 도커를 조작하는 명령어들에 대해 알아보겠습니다.

도커 컴포즈는 docker-compose 명령으로 시작합니다. 마찬가지로 주로 사용되는 명령어 그리고 입문 수준에서 사용되는 명령어들만 정리했습니다.

전체 명령어 및 옵션을 공식 문서에서 확인하실 수 있습니다.

명령어설명
docker-compose updocker-compose.yml에 정의된 설정을 기반으로 모든 service 생성 및 실행
-d 옵션으로 백그라운드 실행
docker-compose down모든 컨테이너와 볼륨, 네트워크 종료 및 제거
docker-compose stop컨테이너만 정지
docker-compose startstop으로 정지된 컨테이너만 재시작
docker-compose restart컨테이너 재시작
docker-compose ps도커 컴포즈로 실행 중인 컨테이너 목록 출력

기본적으로 docker-compose.yml은 해당 프로젝트나 컨테이너 폴더 루트에 넣고 실행합니다. 만약 .yml이 해당 위치에 있지 않거나 다른 이름으로 존재한다면 -f 옵션을 사용해 up을 수행합니다. (삭제 down도 동일함)

docker-compose -f 경로 up [옵션]
profile
Bam
이전 포스트

[Docker] Dockerfile로 이미지 만들기

0개의 댓글