Docker Compose 완벽 가이드 | 멀티 컨테이너·네트워크·볼륨·환경 변수

2026년 4월 7일 · 14분 읽기 · 수정 2026년 4월 7일 중급

이 글의 핵심

Docker Compose로 멀티 컨테이너 앱을 관리하는 완벽 가이드입니다. 서비스 정의, 네트워크, 볼륨, 환경 변수, 프로덕션 설정까지 실전 예제로 정리했습니다.

실무 경험 공유: 개발 환경을 Docker Compose로 표준화하면서, 온보딩 시간을 3일에서 30분으로 단축하고 “내 컴퓨터에서는 되는데” 문제를 완전히 해결한 경험을 공유합니다.

들어가며: “개발 환경 설정이 복잡해요”

실무 문제 시나리오

시나리오 1: PostgreSQL, Redis 설치가 번거로워요
각각 설치하고 설정해야 합니다. Docker Compose는 한 번에 실행합니다.

시나리오 2: 팀원마다 환경이 달라요
버전, 설정이 다릅니다. Docker Compose로 일관성을 유지합니다.

시나리오 3: 여러 컨테이너를 수동으로 실행해요
docker run을 여러 번 실행합니다. Docker Compose는 한 명령으로 실행합니다.

1. Docker Compose란?

핵심 특징

Docker Compose는 멀티 컨테이너 Docker 앱을 정의하고 실행하는 도구입니다.

주요 장점:

간단한 설정: YAML 파일 하나
한 번에 실행: docker compose up
네트워크 자동 생성: 컨테이너 간 통신
볼륨 관리: 데이터 영속성
환경 변수: .env 파일 지원

2. 설치

# Docker Desktop (Windows, macOS)
# Docker Compose 포함됨

# Linux
sudo apt install docker-compose-plugin

# 확인
docker compose version

3. 기본 사용

docker-compose.yml

version: '3.8'

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

명령어

# 시작
docker compose up

# 백그라운드 실행
docker compose up -d

# 중지
docker compose down

# 로그 확인
docker compose logs

# 특정 서비스 로그
docker compose logs web

# 재시작
docker compose restart

4. 실전 예제: 풀스택 앱

# docker-compose.yml
version: '3.8'

services:
  # Frontend (React)
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - REACT_APP_API_URL=http://localhost:8000
    depends_on:
      - backend

  # Backend (FastAPI)
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:secret@db:5432/mydb
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis
    volumes:
      - ./backend:/app

  # Database (PostgreSQL)
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  # Cache (Redis)
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

  # Nginx (Reverse Proxy)
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - frontend
      - backend

volumes:
  postgres-data:
  redis-data:

networks:
  default:
    name: myapp-network

5. 환경 변수

.env 파일

# .env
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb

REDIS_PASSWORD=redis-secret

API_PORT=8000
FRONTEND_PORT=3000

사용

# docker-compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}

6. 네트워크

커스텀 네트워크

services:
  frontend:
    networks:
      - frontend-network

  backend:
    networks:
      - frontend-network
      - backend-network

  db:
    networks:
      - backend-network

networks:
  frontend-network:
  backend-network:

7. 헬스체크

services:
  backend:
    image: myapp/backend
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

8. 프로덕션 설정

docker-compose.prod.yml

version: '3.8'

services:
  backend:
    image: myapp/backend:1.0.0
    restart: always
    environment:
      - NODE_ENV=production
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

  db:
    image: postgres:16
    restart: always
    volumes:
      - /data/postgres:/var/lib/postgresql/data

# 프로덕션 실행
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

정리 및 체크리스트

핵심 요약

Docker Compose: 멀티 컨테이너 앱 관리
간단한 설정: YAML 파일
네트워크: 자동 생성
볼륨: 데이터 영속성
환경 변수: .env 파일
헬스체크: 자동 복구

구현 체크리스트

같이 보면 좋은 글

Kubernetes 실전 가이드
GitHub Actions CI/CD 가이드
Terraform 실전 가이드

이 글에서 다루는 키워드

Docker, Docker Compose, Container, DevOps, Microservices, Infrastructure

자주 묻는 질문 (FAQ)

Q. Docker Compose vs Kubernetes, 어떤 게 나은가요?

A. Docker Compose는 단일 서버용입니다. Kubernetes는 클러스터용입니다. 소규모는 Docker Compose, 대규모는 Kubernetes를 권장합니다.

Q. 프로덕션에서 사용해도 되나요?

A. 소규모 앱은 괜찮지만, 대규모는 Kubernetes를 권장합니다.

Q. Swarm vs Compose, 차이가 뭔가요?

A. Swarm은 오케스트레이션 도구입니다. Compose는 개발 도구입니다. 프로덕션은 Swarm이나 Kubernetes를 사용하세요.

Q. 볼륨 데이터는 어디에 저장되나요?

A. Docker가 관리하는 디렉터리에 저장됩니다. docker volume inspect <volume_name>으로 확인할 수 있습니다.