Docker Compose
2026.10.01 · 28분
1. Docker Compose란?
Docker Compose는 여러 Docker Container의 구성과 실행 방법을 하나의 YAML 파일에 정의하고, 명령어 하나로 함께 관리하게 해주는 도구입니다.
Docker를 직접 사용하면 일반적으로 다음과 같이 Container를 하나씩 실행합니다.
docker build -t my-app .
docker run -d \
--name my-app \
-p 3000:3000 \
-e NODE_ENV=development \
my-appContainer가 하나라면 크게 복잡하지 않습니다.
애플리케이션이 다음처럼 여러 Container로 이루어져 있으면 챙길 것이 많아집니다.
Application
├── Node.js
├── PostgreSQL
└── Redis각 Container에 대해 다음과 같은 설정이 필요할 수 있습니다.
Container 실행
Port 설정
환경 변수 설정
Volume 연결
Network 연결
Container 간 연결이를 모두 docker run 명령어로 관리하면 명령어가 길고 복잡해집니다.
Docker Compose를 사용하면 이러한 설정을 하나의 파일에 작성할 수 있습니다.
compose.yaml
├── App 설정
├── PostgreSQL 설정
├── Redis 설정
├── Network 설정
└── Volume 설정그리고 다음 명령어 하나로 전체 환경을 실행할 수 있습니다.
docker compose up2. Docker Compose가 필요한 이유
예를 들어 다음과 같은 애플리케이션을 개발한다고 가정합니다.
Node.js Application
↓
PostgreSQL
+
RedisDocker Compose를 사용하지 않는다면 각각의 Container를 직접 실행해야 합니다.
먼저 Network를 생성합니다.
docker network create my-networkPostgreSQL을 실행합니다.
docker run -d \
--name postgres \
--network my-network \
-e POSTGRES_PASSWORD=password \
-p 5432:5432 \
postgres:16Redis도 실행합니다.
docker run -d \
--name redis \
--network my-network \
-p 6379:6379 \
redis:7애플리케이션 Image를 생성합니다.
docker build -t my-app .그리고 애플리케이션 Container를 실행합니다.
docker run -d \
--name app \
--network my-network \
-p 3000:3000 \
-e DB_HOST=postgres \
-e REDIS_HOST=redis \
my-app단계가 꽤 많습니다.
Network 생성
↓
PostgreSQL 실행
↓
Redis 실행
↓
Application Build
↓
Application 실행또한 다른 개발자가 프로젝트를 실행하려면 이러한 명령어와 설정을 모두 알아야 합니다.
Docker Compose를 사용하면 이 설정을 파일로 관리할 수 있습니다.
3. compose.yaml
Docker Compose에서는 일반적으로 compose.yaml 파일에 Container 구성을 정의합니다.
예를 들어:
services:
app:
build: .
ports:
- "3000:3000"
environment:
DB_HOST: postgres
REDIS_HOST: redis
depends_on:
- postgres
- redis
postgres:
image: postgres:16
environment:
POSTGRES_PASSWORD: password
volumes:
- postgres-data:/var/lib/postgresql/data
redis:
image: redis:7
volumes:
postgres-data:그리고 다음 명령어를 실행합니다.
docker compose upDocker Compose가 설정을 읽어 필요한 Container들을 구성합니다.
compose.yaml
↓
docker compose up
↓
Docker Compose
│
├── app
│ └── App Container
│
├── postgres
│ └── PostgreSQL Container
│
└── redis
└── Redis Container4. Docker와 Docker Compose의 관계
Docker Compose는 Docker를 대체하는 기술이 아닙니다.
Docker의 기존 동작:
Dockerfile
↓
docker build
↓
Image
↓
docker run
↓
Container은 그대로 존재합니다.
Docker Compose는 이 과정을 설정 파일을 기반으로 대신 관리합니다.
compose.yaml
↓
docker compose up
↓
필요한 Image Build
↓
Container 생성
↓
Network 연결
↓
Volume 연결
↓
Container 실행Docker Compose는 여러 Container의 Build, Run과 관련 설정을 선언적으로 관리하는 도구입니다. Build와 Run 과정 자체는 그대로 남아 있습니다.
5. Dockerfile과 compose.yaml의 차이
두 파일은 역할이 다릅니다.
Dockerfile
Dockerfile은 다음 질문에 대한 답입니다.
"이 애플리케이션의 Docker Image를 어떻게 만들 것인가?"
예:
FROM node:22
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]Dockerfile을 통해:
Source Code
+
Dockerfile
↓
docker build
↓
Docker Image가 만들어집니다.
compose.yaml
Compose 파일은 다음 질문에 대한 답입니다.
"여러 Container를 어떤 설정과 관계로 함께 실행할 것인가?"
예:
services:
app:
build: .
ports:
- "3000:3000"
database:
image: postgres:16
redis:
image: redis:7구조적으로 보면:
Dockerfile
│
│ Image를 어떻게 만들까?
│
↓
App Image
compose.yaml
│
│ Container들을 어떻게 실행할까?
│
├── App Container
├── PostgreSQL Container
└── Redis ContainerDockerfile은 Image를 만드는 방법을, Compose 파일은 Container들을 함께 실행하는 방법을 맡습니다.
6. services
Compose 파일에서 가장 중요한 항목은 services입니다.
services:
app:
...
postgres:
...
redis:
...각 Service는 일반적으로 하나의 Container 구성을 나타냅니다.
services
├── app
│ ↓
│ App Container
│
├── postgres
│ ↓
│ PostgreSQL Container
│
└── redis
↓
Redis Containerapp, postgres, redis와 같은 이름은 개발자가 직접 정할 수 있습니다.
7. build
직접 만든 애플리케이션을 Container로 실행하려면 build를 사용할 수 있습니다.
services:
app:
build: ..은 현재 디렉터리를 Build Context로 사용한다는 의미입니다.
Docker Compose는 현재 디렉터리의 Dockerfile을 이용하여 Image를 Build합니다.
compose.yaml
build: .
↓
Dockerfile
↓
docker build
↓
App Image
↓
App ContainerDockerfile이 다른 위치에 있다면 조금 더 상세하게 지정할 수도 있습니다.
services:
app:
build:
context: .
dockerfile: Dockerfile8. image
이미 만들어져 있는 Docker Image를 사용하는 경우 image를 사용합니다.
예를 들어:
services:
postgres:
image: postgres:16
redis:
image: redis:7stop
docker compose stopContainer를 중지합니다.
Container
Running
↓
Stopped
Container 자체는 존재다시:
docker compose start로 실행할 수 있습니다.
down
docker compose downContainer를 중지하고 제거합니다.
Container
Running
↓
Stopped
↓
Removed필요한 경우 다음 up 실행 시 Container가 다시 생성됩니다.
30. 자주 사용하는 Docker Compose 명령어
| 명령어 | 설명 |
|---|---|
docker compose up | 전체 Service 실행 |
docker compose up -d | 백그라운드 실행 |
docker compose up --build | Image를 Build하면서 실행 |
docker compose down | Container와 Network 종료 및 제거 |
docker compose down -v | Volume까지 함께 제거 |
docker compose stop | Container 중지 |
docker compose start | 중지된 Container 다시 실행 |
여러 Container를 한 번에 관리
기존:
docker run ...
docker run ...
docker run ...Compose:
docker compose up실행 환경을 코드로 관리
긴 Docker 명령어를 문서로 전달할 필요가 없습니다.
"Postgres는 이 명령어로 실행하고
Redis는 이 옵션을 추가하고
Network는 이것을 사용하세요."대신:
compose.yaml파일 자체가 실행 환경에 대한 설명이 됩니다.
팀 개발 환경 통일
프로젝트를 받은 개발자가:
docker compose up만으로 필요한 환경을 실행할 수 있도록 구성할 수 있습니다.
개발자 A ─┐
개발자 B ─┼→ compose.yaml
개발자 C ─┘
↓
동일한 개발 환경복잡한 명령어 감소
다음과 같은 설정을:
Port
Environment
Volume
Network
Image
Build
Dependency
Health Check하나의 YAML 파일에서 관리할 수 있습니다.
34. Docker Compose를 이해할 때 중요한 점
Docker Compose를 새로운 Container 기술이라고 생각할 필요는 없습니다.
Docker의 기본 구조는 여전히:
Dockerfile
↓
Image
↓
Container입니다.
Docker Compose는 그 위에서:
compose.yaml
↓
여러 Container 관리
┌───────────┼───────────┐
↓ ↓ ↓
App Database Redis
│ │ │
└───────────┼───────────┘
↓
Network
+
Volumes처럼 여러 Container와 관련 설정을 하나의 애플리케이션 환경으로 묶어서 관리합니다.
35. Docker와 Docker Compose의 관계 정리
각각을 한 문장씩 정리하면 다음과 같습니다.
Dockerfile
하나의 Docker Image를 어떻게 만들 것인지 정의한다.
Docker Image
Container를 만들기 위한 실행 환경과 애플리케이션의 패키지다.
Docker Container
Image를 실제로 실행한 인스턴스다.
Docker Compose
여러 Container를 어떤 설정과 관계로 함께 실행할 것인지 정의하고 관리한다.
전체 관계를 표현하면 다음과 같습니다.
Dockerfile
│
↓
Image
│
↓
Container
↑
│
Docker Compose
│
┌─────────────┼─────────────┐
│ │ │
Port Volume Network
│ │ │
└─────────────┼─────────────┘
│
compose.yaml