Docker Compose를 사용하려면 가장 먼저 이해해야 하는 것이 docker-compose.yml 파일 구조입니다.

Docker Compose는 YAML 형식의 설정 파일을 통해 Container 환경을 정의합니다.

기본 구조:

services:

  service-name:

    image:

    ports:

    volumes:

    environment:

이 파일 하나로 Container 생성부터 Network 연결, Volume 설정, 환경 변수 관리까지 모두 제어할 수 있습니다.

기존 Docker 실행 방식:

docker run nginx
docker run mysql
docker run redis

여러 명령 필요

Docker Compose 방식:

services:

  nginx:

    image: nginx


  mysql:

    image: mysql


  redis:

    image: redis

실행:

docker compose up

결과:

Nginx Container 생성

↓

MySQL Container 생성

↓

Redis Container 생성

이번 글에서는 Docker Compose YAML의 기본 구조부터 Service, Image, Container 이름, Port, Volume, Environment 설정까지 서버 운영에 필요한 핵심 내용을 알아보겠습니다.

Docker Compose YAML 기본 구조

Docker Compose 파일은 크게 다음 구조로 구성됩니다.

services:

networks:

volumes:

각 역할:

항목	역할
services	Container 정의
networks	Container 연결
volumes	데이터 저장

기본 예제:

services:

  web:

    image: nginx


  database:

    image: mysql

구조:

docker-compose.yml

↓

Services

↓

Containers

↓

Networks / Volumes

Docker Compose services란?

services는 실행할 Container를 정의하는 가장 중요한 영역입니다.

예:

services:

  nginx:

    image: nginx

의미:

Service 이름

↓

nginx

↓

Container 생성

하나의 Service는 하나의 Container 그룹을 의미합니다.

예:

services:

  app:

    image: node


  db:

    image: mysql

결과:

app Container

+

db Container

두 개의 서비스 실행

Docker Compose image 설정 방법

image는 사용할 Docker Image를 지정합니다.

예:

services:

  web:

    image: nginx

의미:

Docker Hub

↓

nginx Image 다운로드

↓

Container 생성

버전 지정:

services:

  web:

    image: nginx:1.27

권장:

nginx:1.27

비권장:

nginx:latest

이유:

Version 변경 추적 어려움
예상하지 못한 업데이트 발생 가능

Docker Compose container_name 설정

Container 이름을 직접 지정할 수 있습니다.

예:

services:

  web:

    image: nginx

    container_name: my-nginx

확인:

docker ps

결과:

my-nginx

장점:

관리 편리
로그 확인 쉬움

주의:

대규모 환경에서는 자동 이름 사용을 권장하는 경우도 있습니다.

Docker Compose ports 설정

Container Port와 Host Port를 연결합니다.

구조:

외부 사용자

↓

Host Port

↓

Container Port

예:

services:

  web:

    image: nginx

    ports:

      - "8080:80"

의미:

접속:

localhost:8080

실제 흐름:

사용자

↓

8080 Port

↓

Nginx 80 Port

↓

Container

Docker Compose volumes 설정

Volume은 Container 데이터를 저장하는 기능입니다.

문제:

Container 삭제:

Container 삭제

↓

내부 데이터 삭제

Volume 사용:

Container 삭제

↓

Volume 유지

↓

데이터 보존

예:

services:

  mysql:

    image: mysql

    volumes:

      - mysql-data:/var/lib/mysql


volumes:

  mysql-data:

구조:

Host

↓

Volume

↓

Database Data

Docker Compose environment 설정

환경 변수는 Container 설정값을 전달합니다.

예:

services:

  database:

    image: mysql

    environment:

      MYSQL_ROOT_PASSWORD: password

MySQL Container:

MYSQL_ROOT_PASSWORD

↓

Database 초기 비밀번호 설정

여러 개 설정:

environment:

  MYSQL_DATABASE: app

  MYSQL_USER: user

  MYSQL_PASSWORD: password

Docker Compose restart 설정

서버 재부팅 후 Container 자동 실행 설정입니다.

예:

services:

  web:

    image: nginx

    restart: always

옵션:

no

기본값

restart: no

always

항상 재시작

restart: always

unless-stopped

직접 종료 전까지 실행

restart: unless-stopped

on-failure

오류 발생 시 재시작

restart: on-failure

Production 서버에서는:

restart: unless-stopped

를 많이 사용합니다.

Docker Compose depends_on 설정

Service 실행 순서를 지정합니다.

예:

services:

  app:

    image: node

    depends_on:

      - db


  db:

    image: mysql

실행 순서:

Database 시작

↓

Application 시작

주의:

depends_on은 실행 순서만 관리하며 완전한 Health Check는 아닙니다.

Docker Compose 전체 예제

실제 서버 기본 구성:

services:

  nginx:

    image: nginx:latest

    ports:

      - "80:80"


  app:

    image: node:20

    ports:

      - "3000:3000"


  database:

    image: mysql:8

    environment:

      MYSQL_ROOT_PASSWORD: password

    volumes:

      - mysql-data:/var/lib/mysql


volumes:

  mysql-data:

구조:

사용자

↓

Nginx

↓

Node Application

↓

MySQL Database

Docker Compose YAML 작성 시 주의사항

첫 번째는 들여쓰기가 중요합니다.

YAML은 공백으로 구조를 구분합니다.

잘못된 예:

services:
web:
image: nginx

올바른 예:

services:

  web:

    image: nginx

두 번째는 Version 관리입니다.

예:

image: mysql:8

세 번째는 Production 환경에서 Password를 직접 작성하지 않는 것이 좋습니다.

권장:

.env 파일 사용

또는:

Secret 관리

Docker Compose YAML 작성 Best Practice

자주 묻는 질문

docker-compose.yml은 꼭 필요한가요?

Docker Compose를 사용하려면 기본 설정 파일 역할을 하기 때문에 필요합니다.

Service와 Container 차이는 무엇인가요?

Service는 설정 단위이고, Container는 실제 실행되는 객체입니다.

여러 Container를 한번에 실행할 수 있나요?

가능합니다.

docker compose up 명령 하나로 전체 Service를 실행합니다.

Production 서버에서도 사용할 수 있나요?