Docker Compose 활용: 다중 서비스 로컬 개발 환경 효율적으로 구축하는 가이드

Docker Compose를 활용하여 복잡한 다중 서비스 애플리케이션의 로컬 개발 환경을 쉽고 효율적으로 구축하는 방법을 상세히 안내합니다. 컨테이너 기반 개발의 생산성을 극대화하세요.

개발자에게 있어 로컬 개발 환경 설정은 프로젝트의 시작이자 생산성에 직접적인 영향을 미치는 중요한 과정이다. 특히 마이크로서비스 아키텍처나 다중 서비스 애플리케이션이 보편화되면서, 여러 개의 서비스(백엔드 API, 데이터베이스, 캐시, 메시지 큐 등)를 개별적으로 구동하고 관리하는 복잡성은 점점 증가하고 있다. 이러한 환경에서 각 서비스의 의존성을 해결하고 일관된 개발 환경을 유지하는 것은 상당한 시간과 노력을 요구하는 도전 과제가 될 수 있다.

본 가이드는 이러한 문제에 대한 강력한 해결책으로 Docker Compose를 제시한다. Docker Compose는 여러 개의 Docker 컨테이너를 정의하고 실행하는 도구로, YAML 파일을 통해 다중 컨테이너 애플리케이션의 모든 서비스를 한 번에 구성하고 관리할 수 있도록 돕는다. 이를 통해 개발자는 복잡한 설정 과정에서 벗어나 핵심 개발에 집중할 수 있으며, 팀원 간의 환경 불일치 문제를 최소화하여 개발 생산성을 크게 향상시킬 수 있다. 이 글에서는 Docker Compose의 기본 개념부터 실제 로컬 개발 환경 구축 실습, 그리고 고급 활용 팁까지 상세하게 다룰 예정이다.

📑 목차

• 1. 다중 서비스 개발 환경의 도전과 Docker Compose의 역할
• 1.1. 복잡성 증가와 환경 불일치 문제
• 1.2. Docker Compose가 제공하는 해결책
• 2. Docker Compose 기본 개념 이해
• 2.1. docker-compose.yml 파일의 구조
• 2.2. 서비스, 네트워크, 볼륨 정의
• 3. 로컬 개발 환경 구축을 위한 Docker Compose 설정 실습
• 3.1. 예시 시나리오: 웹 애플리케이션 + 데이터베이스 + 캐시 서버
• 3.2. docker-compose.yml 파일 작성 가이드
• 4. Docker Compose 명령어 활용 및 개발 워크플로우 최적화
• 4.1. 핵심 명령어 (`up`, `down`, `ps`, `logs`, `exec`)
• 4.2. 개발 중 실시간 반영 및 디버깅 팁
• 5. 고급 설정 및 모범 사례
• 5.1. 환경 변수 관리 및 `.env` 파일 활용
• 5.2. 볼륨 마운트를 통한 코드 실시간 동기화
• 5.3. 네트워크 설정 및 서비스 간 통신
• 6. Docker Compose vs. 단일 Docker 컨테이너: 비교 분석
• 7. 결론: Docker Compose로 개발 생산성을 극대화하다

Image by 2427999 on Pixabay

1. 다중 서비스 개발 환경의 도전과 Docker Compose의 역할

현대의 소프트웨어 개발은 단일 모놀리식 애플리케이션보다는 여러 개의 독립적인 서비스로 구성된 분산 시스템 형태로 진화하고 있다. 이러한 다중 서비스 아키텍처는 각 서비스의 독립적인 배포, 확장성, 기술 스택 유연성 등의 장점을 제공하지만, 동시에 로컬 개발 환경 설정에 있어 새로운 도전 과제들을 야기한다.

1.1. 복잡성 증가와 환경 불일치 문제

일반적인 다중 서비스 애플리케이션은 다음과 같은 구성 요소를 포함할 수 있다.

• 프론트엔드 서비스: React, Vue, Angular 등
• 백엔드 API 서비스: Node.js, Spring Boot, Django, Flask 등
• 데이터베이스: PostgreSQL, MySQL, MongoDB, Redis 등
• 메시지 큐: Kafka, RabbitMQ 등
• 캐시 서버: Redis, Memcached 등
• 기타 유틸리티: Nginx (리버스 프록시), Kibana (로그 분석) 등

이러한 구성 요소들을 로컬 머신에 개별적으로 설치하고 관리하는 것은 매우 번거로운 작업이다. 각 서비스마다 다른 버전의 런타임, 라이브러리, 환경 변수 설정이 필요할 수 있으며, 이들 간의 의존성 충돌이나 포트 충돌 문제도 빈번하게 발생한다. 특히 여러 개발자가 하나의 프로젝트에 참여할 때, 각 개발자의 로컬 환경이 미묘하게 달라 발생하는 "내 컴퓨터에서는 되는데..."와 같은 환경 불일치 문제는 개발 프로세스를 지연시키고 디버깅에 불필요한 시간을 소모하게 만든다.

또한, 새로운 팀원이 프로젝트에 합류했을 때 개발 환경을 설정하는 데만 며칠이 소요되기도 하며, 이는 온보딩 비용을 증가시키는 주요 원인으로 작용한다.

1.2. Docker Compose가 제공하는 해결책

Docker Compose는 이러한 다중 서비스 개발 환경의 복잡성을 해결하기 위한 핵심 도구로 부상하였다. Docker Compose는 다음과 같은 방식으로 개발자에게 이점을 제공한다.

• 단일 파일 기반 정의: docker-compose.yml이라는 하나의 YAML 파일을 사용하여 애플리케이션을 구성하는 모든 서비스, 네트워크, 볼륨 등을 명확하게 정의할 수 있다. 이는 복잡한 환경 설정을 코드화하여 관리하는 IaC (Infrastructure as Code) 원칙을 따른다.
• 일관된 환경 유지: 모든 팀원이 동일한 docker-compose.yml 파일을 사용하여 개발 환경을 구축하므로, OS나 로컬 설정에 관계없이 동일한 개발 환경을 보장할 수 있다. 이는 환경 불일치 문제를 근본적으로 해소한다.
• 간편한 시작 및 종료: 단일 명령(docker compose up)으로 정의된 모든 서비스를 한 번에 시작하고, docker compose down 명령으로 모든 서비스를 깨끗하게 종료할 수 있다. 이는 개발 워크플로우를 극적으로 단순화한다.
• 버전 관리 용이성: docker-compose.yml 파일은 코드와 함께 버전 관리 시스템(Git 등)에 커밋되므로, 환경 설정의 변경 이력을 추적하고 필요에 따라 이전 상태로 되돌릴 수 있다.
• 자원 효율성: 각 서비스를 컨테이너로 격리하여 실행하므로, 로컬 머신에 직접 여러 미들웨어를 설치할 필요가 없으며, 필요한 경우에만 자원을 할당하여 사용할 수 있다.

결론적으로, Docker Compose는 다중 서비스 애플리케이션의 로컬 개발 환경 구축을 표준화하고 자동화하여 개발자의 생산성을 향상시키고 팀 협업의 효율성을 증대시키는 데 필수적인 도구로 판단된다.

2. Docker Compose 기본 개념 이해

Docker Compose를 효과적으로 활용하기 위해서는 그 핵심 구성 요소와 작동 방식을 이해하는 것이 중요하다. Docker Compose는 기본적으로 docker-compose.yml이라는 YAML 파일을 통해 애플리케이션 스택을 정의하며, 이 파일은 서비스, 네트워크, 볼륨 세 가지 주요 섹션으로 구성된다.

2.1. docker-compose.yml 파일의 구조

docker-compose.yml 파일은 Docker Compose 애플리케이션의 청사진이다. 이 파일은 애플리케이션을 구성하는 각 서비스의 이미지, 포트 매핑, 환경 변수, 의존성 등을 명시한다. 기본적인 구조는 다음과 같다.

version: '3.8' # Compose 파일 형식 버전 지정
services:
  web: # 서비스 이름 (컨테이너 이름으로도 사용 가능)
    image: nginx:latest # 사용할 Docker 이미지
    ports:
      - "80:80" # 호스트 포트:컨테이너 포트
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf # 호스트 경로:컨테이너 경로 (볼륨 마운트)
    depends_on: # 의존성 정의
      - api
  api:
    build: . # 현재 디렉토리의 Dockerfile을 사용하여 이미지 빌드
    ports:
      - "5000:5000"
    environment: # 환경 변수 설정
      DATABASE_URL: postgres://user:password@db:5432/mydb
    networks: # 서비스가 속할 네트워크 지정
      - app-network
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db_data:/var/lib/postgresql/data # named volume 사용
    networks:
      - app-network

networks: # 네트워크 정의
  app-network:
    driver: bridge # 브릿지 네트워크 드라이버 사용

volumes: # 볼륨 정의
  db_data: # named volume 이름

여기서 version은 Compose 파일의 형식을 지정하며, 일반적으로 최신 안정 버전인 3.x를 사용한다. services 섹션은 애플리케이션을 구성하는 핵심 서비스들을 정의하는 공간이다.

2.2. 서비스, 네트워크, 볼륨 정의

서비스 (Services): services 섹션은 Docker Compose의 핵심이다. 각 서비스는 독립적인 컨테이너로 실행될 애플리케이션의 구성 요소를 나타낸다. 위 예시에서는 web, api, db 세 가지 서비스를 정의하고 있다. 각 서비스는 다음과 같은 주요 속성을 가질 수 있다.

• image: Docker Hub 또는 사설 레지스트리에서 가져올 Docker 이미지 이름과 태그를 지정한다 (예: nginx:latest).
• build: 현재 디렉토리의 Dockerfile을 사용하여 이미지를 직접 빌드하도록 지시한다. 이는 로컬 코드 기반의 애플리케이션에 유용하다.
• ports: 호스트 머신의 포트와 컨테이너 내부의 포트를 매핑하여 외부에서 컨테이너 서비스에 접근할 수 있도록 한다. (예: "80:80")
• volumes: 호스트 머신의 경로 또는 Named Volume을 컨테이너 내부의 경로에 마운트한다. 이는 데이터 지속성 유지 및 코드 실시간 동기화에 필수적이다.
• environment: 컨테이너 내부에서 사용할 환경 변수를 설정한다. 데이터베이스 연결 정보나 API 키 등 민감하지 않은 설정 값에 활용된다.
• depends_on: 서비스 간의 의존성을 정의한다. 예를 들어, web 서비스가 api 서비스에 의존한다면, api 서비스가 먼저 시작된 후에 web 서비스가 시작되도록 보장한다. 이는 서비스 시작 순서를 제어하는 데 도움이 된다.
• networks: 서비스가 연결될 네트워크를 지정한다.

네트워크 (Networks): Docker Compose는 기본적으로 모든 서비스에 대해 하나의 기본 브릿지 네트워크를 생성하고 연결한다. 그러나 명시적으로 networks 섹션을 정의하여 사용자 정의 네트워크를 생성할 수 있다. 사용자 정의 네트워크를 사용하면 서비스 간의 격리 수준을 높이고, 서비스 이름을 사용하여 컨테이너 간에 통신할 수 있다. 예를 들어, api 서비스에서 db 서비스에 접근할 때 IP 주소 대신 db라는 서비스 이름을 사용할 수 있다. 이는 컨테이너의 IP 주소가 변경되어도 코드를 수정할 필요가 없게 하여 유연성을 제공한다.

볼륨 (Volumes): 컨테이너는 기본적으로 휘발성이다. 컨테이너가 삭제되면 그 안에 저장된 데이터도 사라진다. 볼륨은 이러한 문제점을 해결하기 위해 컨테이너의 데이터를 호스트 머신에 영구적으로 저장하는 메커니즘을 제공한다. Docker Compose에서는 두 가지 주요 볼륨 유형을 사용할 수 있다.

• 바인드 마운트 (Bind Mounts): 호스트 머신의 특정 경로를 컨테이너 내부 경로에 직접 연결한다. 개발 중인 소스 코드를 컨테이너와 동기화하는 데 매우 유용하며, 호스트 파일 시스템의 변경 사항이 즉시 컨테이너에 반영된다. (예: ./app:/usr/src/app)
• 네임드 볼륨 (Named Volumes): Docker가 관리하는 볼륨으로, 호스트 파일 시스템의 특정 위치에 구애받지 않고 이름으로 관리된다. 주로 데이터베이스 데이터와 같이 영구적으로 보존해야 하는 데이터에 사용된다. (예: db_data:/var/lib/postgresql/data)

이러한 요소들을 조합하여 docker-compose.yml 파일을 작성함으로써, 복잡한 다중 서비스 애플리케이션의 로컬 개발 환경을 명확하고 일관성 있게 정의할 수 있다.

3. 로컬 개발 환경 구축을 위한 Docker Compose 설정 실습

이제 이론적 이해를 바탕으로 실제 Docker Compose를 활용하여 다중 서비스 로컬 개발 환경을 구축하는 실습 예시를 살펴보자. 다음 시나리오는 일반적인 웹 애플리케이션 스택을 반영한다.

3.1. 예시 시나리오: 웹 애플리케이션 + 데이터베이스 + 캐시 서버

우리는 다음과 같은 서비스로 구성된 웹 애플리케이션의 개발 환경을 구축할 것이다.

• 백엔드 API 서버: Node.js 기반의 Express 애플리케이션으로, 포트 3000번을 사용한다.
• 데이터베이스: PostgreSQL 데이터베이스 서버로, 영구적인 데이터 저장을 위해 볼륨을 사용한다.
• 캐시 서버: Redis 서버로, 세션 관리나 데이터 캐싱에 활용된다.

이 세 가지 서비스는 서로 통신하며 하나의 애플리케이션 스택을 구성한다. 로컬 개발 시에는 백엔드 코드의 변경 사항이 즉시 반영되도록 바인드 마운트를 설정할 것이다.

3.2. docker-compose.yml 파일 작성 가이드

프로젝트 루트 디렉토리에 docker-compose.yml 파일을 생성하고 다음 내용을 작성한다.

# docker-compose.yml
version: '3.8'

services:
  # 1. 백엔드 API 서비스 (Node.js Express)
  backend:
    build:
      context: ./backend # backend 디렉토리의 Dockerfile을 사용하여 이미지 빌드
      dockerfile: Dockerfile
    ports:
      - "3000:3000" # 호스트 3000 포트를 컨테이너 3000 포트에 매핑
    volumes:
      - ./backend:/app # 호스트의 backend 디렉토리를 컨테이너 /app에 마운트 (코드 동기화)
      - /app/node_modules # node_modules는 호스트에서 마운트하지 않도록 예외 처리
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://user:password@db:5432/mydatabase
      REDIS_HOST: redis
      REDIS_PORT: 6379
    depends_on:
      - db # db 서비스가 먼저 시작되도록 의존성 지정
      - redis # redis 서비스가 먼저 시작되도록 의존성 지정
    networks:
      - app-network

  # 2. PostgreSQL 데이터베이스 서비스
  db:
    image: postgres:13-alpine # 경량 PostgreSQL 이미지 사용
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - pg_data:/var/lib/postgresql/data # 데이터 지속성을 위한 Named Volume
    networks:
      - app-network
    healthcheck: # DB 준비 상태를 확인하는 헬스체크 추가
      test: ["CMD-SHELL", "pg_isready -U user -d mydatabase"]
      interval: 5s
      timeout: 5s
      retries: 5

  # 3. Redis 캐시 서버 서비스
  redis:
    image: redis:6-alpine # 경량 Redis 이미지 사용
    volumes:
      - redis_data:/data # 데이터 지속성을 위한 Named Volume (선택 사항)
    networks:
      - app-network

networks:
  app-network:
    driver: bridge # 모든 서비스가 연결될 사용자 정의 브릿지 네트워크

volumes:
  pg_data: # PostgreSQL 데이터를 위한 Named Volume
  redis_data: # Redis 데이터를 위한 Named Volume (선택 사항)

백엔드 서비스용 Dockerfile (./backend/Dockerfile):

# ./backend/Dockerfile
FROM node:16-alpine # Node.js 런타임 이미지 사용
WORKDIR /app # 작업 디렉토리 설정
COPY package*.json ./ # 패키지 의존성 파일 복사
RUN npm install # 의존성 설치
COPY . . # 모든 소스 코드 복사
CMD ["npm", "run", "dev"] # 개발 서버 실행 명령어

주요 설정 설명:

• backend 서비스:
  • build: ./backend 디렉토리의 Dockerfile을 사용하여 이미지를 빌드한다. 이는 로컬에서 개발 중인 Node.js 애플리케이션 코드를 컨테이너화하는 표준 방식이다.
  • ports: "3000:3000": 호스트의 3000번 포트를 컨테이너의 3000번 포트에 매핑하여 로컬 브라우저에서 http://localhost:3000으로 백엔드 API에 접근할 수 있도록 한다.
  • volumes: ./backend:/app: 로컬 backend 디렉토리를 컨테이너의 /app 디렉토리에 마운트한다. 이 설정 덕분에 로컬에서 소스 코드를 수정하면 컨테이너 내부의 코드도 자동으로 업데이트되어 개발 서버가 재시작되거나 변경 사항을 반영할 수 있다.
  • volumes: /app/node_modules: node_modules 디렉토리는 컨테이너 내부에서 생성된 것을 유지하고 호스트에서 마운트하지 않도록 예외 처리한다. 이는 호스트와 컨테이너의 OS 환경 차이로 인한 의존성 문제를 방지하고, 성능 저하를 막는 일반적인 패턴이다.
  • environment: 데이터베이스 및 Redis 연결 정보를 환경 변수로 전달한다. DATABASE_URL의 호스트 이름이 db로 설정된 것에 주목하라. 이는 Docker Compose가 서비스 이름을 내부 DNS로 자동 등록해주기 때문에 가능하다. 마찬가지로 REDIS_HOST는 redis로 설정한다.
  • depends_on: db와 redis 서비스가 먼저 시작되어야 backend 서비스가 정상적으로 동작할 수 있으므로 의존성을 명시한다.
• db 서비스:
  • image: postgres:13-alpine: 경량 버전의 PostgreSQL 이미지를 사용한다.
  • environment: 데이터베이스 초기 설정(DB 이름, 사용자, 비밀번호)을 환경 변수로 전달한다.
  • volumes: pg_data:/var/lib/postgresql/data: pg_data라는 Named Volume을 사용하여 PostgreSQL 데이터를 영구적으로 저장한다. 컨테이너가 삭제되어도 데이터는 보존된다.
  • healthcheck: 데이터베이스가 완전히 시작되고 연결을 받을 준비가 되었는지 확인하는 헬스체크를 정의한다. depends_on은 서비스의 시작 순서만 보장할 뿐, 서비스 내부의 애플리케이션이 완전히 준비되었음을 보장하지 않으므로, 헬스체크는 더욱 견고한 환경 구축에 기여한다.
• redis 서비스:
  • image: redis:6-alpine: 경량 버전의 Redis 이미지를 사용한다.
  • volumes: redis_data:/data: Redis 데이터도 영구적으로 보존할 필요가 있다면 Named Volume을 사용할 수 있다. (선택 사항)
• networks 및 volumes 섹션:
  • app-network: 모든 서비스가 이 네트워크에 연결되어 서로 서비스 이름으로 통신할 수 있도록 한다.
  • pg_data, redis_data: 각 서비스에서 사용할 Named Volume을 정의한다.

이 docker-compose.yml 파일과 Dockerfile을 사용하면 단일 명령어로 복잡한 다중 서비스 로컬 개발 환경을 완벽하게 구축하고 관리할 수 있다.

Image by Daria-Yakovleva on Pixabay

4. Docker Compose 명령어 활용 및 개발 워크플로우 최적화

Docker Compose 파일이 준비되었다면, 이제 CLI 명령어를 통해 정의된 서비스를 관리하고 개발 워크플로우를 최적화할 수 있다. 핵심 명령어들을 익히고 효과적으로 활용하는 방법을 살펴보자.

4.1. 핵심 명령어 (`up`, `down`, `ps`, `logs`, `exec`)

1. 서비스 시작: `docker compose up`

docker-compose.yml 파일이 있는 디렉토리에서 이 명령어를 실행하면, 파일에 정의된 모든 서비스가 빌드되고 시작된다. 가장 일반적으로 사용되는 옵션은 다음과 같다.

• docker compose up -d: 모든 서비스를 백그라운드(detached mode)에서 실행한다. 터미널을 점유하지 않아 다른 작업을 동시에 수행할 수 있다. 개발 환경에서 가장 많이 사용되는 방식이다.
• docker compose up --build: 이미지가 변경되었거나 Dockerfile이 수정되었을 때, 이미지를 다시 빌드한 후 서비스를 시작한다.
• docker compose up --force-recreate: 기존 컨테이너를 강제로 재생성하여 서비스를 시작한다. 컨테이너 설정이 변경되었으나 새 이미지 빌드가 필요 없을 때 유용하다.

예시:

$ docker compose up -d --build

이 명령은 백엔드 서비스의 Dockerfile이 수정되었을 경우 이미지를 새로 빌드하고, 모든 서비스를 백그라운드에서 실행한다. 모든 컨테이너가 정상적으로 시작되면, http://localhost:3000(백엔드)으로 접근하여 테스트할 수 있다.

2. 서비스 종료: `docker compose down`

실행 중인 모든 서비스를 중지하고 관련 컨테이너, 네트워크, 볼륨(명시적으로 제거하도록 설정한 경우)을 삭제한다.

• docker compose down: 컨테이너와 네트워크를 중지 및 제거한다. Named Volume은 기본적으로 제거되지 않는다.
• docker compose down -v: 컨테이너, 네트워크와 함께 Named Volume도 제거한다. 데이터베이스 데이터를 완전히 초기화해야 할 때 유용하다.
• docker compose down --rmi all: 컨테이너뿐만 아니라 Compose 파일에 정의된 서비스들이 사용하는 모든 이미지도 제거한다.

예시:

$ docker compose down -v

이 명령은 모든 서비스 컨테이너를 중지하고 제거하며, 데이터베이스 및 Redis의 Named Volume에 저장된 데이터도 함께 삭제한다.

3. 서비스 상태 확인: `docker compose ps`

현재 Docker Compose 프로젝트 내에서 실행 중인 모든 서비스의 상태를 보여준다. 각 컨테이너의 이름, 명령어, 상태, 포트 매핑 등을 확인할 수 있다.

예시:

$ docker compose ps
NAME                COMMAND                  SERVICE             STATUS              PORTS
my-app-backend-1    "docker-entrypoint.s…"   backend             running             0.0.0.0:3000->3000/tcp
my-app-db-1         "docker-entrypoint.s…"   db                  running             5432/tcp
my-app-redis-1      "docker-entrypoint.s…"   redis               running             6379/tcp

4. 로그 확인: `docker compose logs`

실행 중인 서비스 컨테이너들의 로그를 출력한다. 디버깅이나 서비스 동작 상태를 모니터링할 때 필수적이다.

• docker compose logs: 모든 서비스의 로그를 통합하여 출력한다.
• docker compose logs -f: 실시간으로 로그를 계속해서 출력한다 (follow mode).
• docker compose logs backend: 특정 서비스(예: backend)의 로그만 출력한다.
• docker compose logs --tail 100 backend: 특정 서비스의 마지막 100줄 로그만 출력한다.

예시:

$ docker compose logs -f backend

이 명령은 백엔드 서비스의 로그를 실시간으로 추적하여 출력한다.

5. 컨테이너 내부 명령어 실행: `docker compose exec`

실행 중인 특정 서비스 컨테이너 내부에서 명령어를 실행할 수 있다. 컨테이너 내부 환경을 확인하거나, 데이터베이스 쉘에 접속하는 등의 작업에 유용하다.

• docker compose exec db psql -U user mydatabase: db 서비스 컨테이너 내부에서 psql 명령어를 실행하여 mydatabase에 접속한다.
• docker compose exec backend bash: backend 서비스 컨테이너 내부로 bash 쉘을 통해 접속한다.

예시:

$ docker compose exec db psql -U user mydatabase

이 명령을 통해 데이터베이스 컨테이너에 접속하여 SQL 쿼리를 실행할 수 있다.

4.2. 개발 중 실시간 반영 및 디버깅 팁

1. 코드 실시간 동기화 (Hot Reloading):

volumes 설정에서 바인드 마운트를 올바르게 구성했다면, 호스트 머신에서 소스 코드를 수정할 때 컨테이너 내부의 코드도 즉시 업데이트된다. 대부분의 최신 웹 프레임워크는 파일 변경을 감지하여 자동으로 애플리케이션을 재시작하거나 핫 리로드 기능을 제공하므로, 개발자는 컨테이너를 재시작할 필요 없이 로컬에서 코드를 수정하며 즉시 결과를 확인할 수 있다. 예를 들어, Node.js 애플리케이션의 경우 nodemon과 같은 도구를 사용하여 파일 변경 시 서버를 자동으로 재시작하도록 설정하는 것이 일반적이다.

2. 효과적인 로그 활용:

docker compose logs -f [서비스명] 명령은 개발 중 디버깅에 매우 중요하다. 특정 서비스에서 발생하는 오류나 동작 흐름을 실시간으로 파악할 수 있기 때문이다. 여러 서비스의 로그를 동시에 보고 싶다면 특정 서비스명을 생략하거나, 여러 터미널을 열어 각 서비스의 로그를 개별적으로 추적할 수 있다.

3. 컨테이너 내부 환경 탐색:

문제가 발생했을 때 docker compose exec [서비스명] bash 또는 sh 명령어로 컨테이너 내부에 접속하여 직접 파일 시스템을 탐색하거나, 환경 변수를 확인하거나, 특정 명령어를 수동으로 실행해보는 것은 문제 해결에 큰 도움이 된다.

4. 재시작 정책 설정:

서비스 정의에 restart: always와 같은 재시작 정책을 추가하면, 컨테이너가 비정상적으로 종료되었을 때 자동으로 다시 시작되어 개발 중에도 서비스 가용성을 높일 수 있다. 하지만 개발 단계에서는 불필요한 자동 재시작이 오히려 디버깅을 방해할 수 있으므로, restart: on-failure 또는 no를 고려하는 것도 좋다.

services:
  backend:
    # ...
    restart: on-failure # 컨테이너가 실패했을 때만 재시작

이러한 명령어와 팁들을 통해 Docker Compose 기반의 로컬 개발 환경을 더욱 효율적으로 관리하고, 개발 생산성을 극대화할 수 있다.

5. 고급 설정 및 모범 사례

Docker Compose는 기본적인 서비스 정의 외에도 다양한 고급 설정을 통해 더욱 유연하고 견고한 로컬 개발 환경을 구축할 수 있도록 지원한다. 몇 가지 중요한 고급 설정과 모범 사례를 살펴보자.

5.1. 환경 변수 관리 및 `.env` 파일 활용

docker-compose.yml 파일 내부에 직접 환경 변수를 정의하는 것은 간단하지만, 민감한 정보(예: 데이터베이스 비밀번호, API 키)를 코드 저장소에 직접 노출하는 것은 보안상 바람직하지 않다. 또한, 개발 환경과 프로덕션 환경에서 다른 값을 사용해야 할 경우 유연성이 떨어진다.

이러한 문제를 해결하기 위해 Docker Compose는 .env 파일을 통한 환경 변수 로딩을 지원한다. docker-compose.yml 파일과 같은 디렉토리에 .env 파일을 생성하고 환경 변수를 정의하면, Compose는 자동으로 해당 변수들을 로드하여 docker-compose.yml 파일 내에서 사용할 수 있게 한다.

.env 파일 예시:

# .env
POSTGRES_USER=dev_user
POSTGRES_PASSWORD=dev_password
POSTGRES_DB=dev_database
REDIS_HOST=redis
REDIS_PORT=6379

docker-compose.yml 파일 수정 예시:

services:
  backend:
    # ...
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      REDIS_HOST: ${REDIS_HOST}
      REDIS_PORT: ${REDIS_PORT}
    # ...
  db:
    image: postgres:13-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    # ...

.env 파일은 일반적으로 .gitignore에 추가하여 버전 관리 시스템에서 제외하며, 각 개발자는 자신의 로컬 환경에 맞는 .env 파일을 생성하여 사용한다. 이는 보안을 강화하고 환경별 설정 관리를 용이하게 한다.

5.2. 볼륨 마운트를 통한 코드 실시간 동기화

이전 섹션에서 언급했듯이, 바인드 마운트는 로컬 개발에서 코드 실시간 동기화를 위해 필수적이다. volumes: ./backend:/app과 같은 설정을 통해 호스트의 개발 코드 변경 사항이 컨테이너에 즉시 반영되도록 할 수 있다.

하지만 Node.js 프로젝트의 node_modules와 같이 컨테이너 내부에서 설치된 의존성 파일들은 호스트와 컨테이너 간의 OS 차이로 인해 문제가 발생할 수 있다. 이를 해결하기 위해 익명 볼륨 (Anonymous Volume)을 활용하여 node_modules 디렉토리만 마운트 예외 처리하는 기법이 일반적이다.

services:
  backend:
    volumes:
      - ./backend:/app # 프로젝트 코드는 호스트에서 마운트
      - /app/node_modules # 컨테이너 내부의 node_modules는 호스트에서 마운트하지 않음

이 설정은 Docker Compose에게 /app/node_modules 경로에 대해 익명 볼륨을 생성하도록 지시한다. 이렇게 하면 호스트의 node_modules 디렉토리가 컨테이너 내부의 node_modules를 덮어쓰지 않고, 컨테이너 내부에서 설치된 의존성들이 독립적으로 유지된다.

5.3. 네트워크 설정 및 서비스 간 통신

Docker Compose는 기본적으로 서비스들을 하나의 브릿지 네트워크에 연결하여 서비스 이름으로 통신할 수 있도록 한다. 그러나 복잡한 애플리케이션의 경우 여러 개의 사용자 정의 네트워크를 생성하여 서비스 간의 통신을 더욱 세밀하게 제어할 수 있다.

networks:
  frontend-network:
    driver: bridge
  backend-network:
    driver: bridge

services:
  frontend:
    # ...
    networks:
      - frontend-network # 프론트엔드는 프론트엔드 네트워크에만 연결
  backend:
    # ...
    networks:
      - frontend-network # 백엔드는 프론트엔드와 백엔드 네트워크에 모두 연결
      - backend-network
  db:
    # ...
    networks:
      - backend-network # DB는 백엔드 네트워크에만 연결

위 예시에서는 frontend-network와 backend-network 두 개의 네트워크를 정의했다. frontend 서비스는 frontend-network에만 연결되어 backend 서비스와 통신하고, db 서비스는 backend-network에만 연결되어 backend 서비스와 통신한다. backend 서비스는 두 네트워크에 모두 연결되어 프론트엔드와 DB 모두와 통신할 수 있다. 이렇게 하면 불필요한 서비스 간의 직접적인 접근을 막아 보안성을 높일 수 있다.

이러한 고급 설정과 모범 사례들을 적용함으로써, 개발자는 Docker Compose를 통해 더욱 안정적이고 효율적인 다중 서비스 로컬 개발 환경을 구축할 수 있다.

Image by Olga_Fil on Pixabay

6. Docker Compose vs. 단일 Docker 컨테이너: 비교 분석

Docker Compose는 단일 Docker 컨테이너를 다루는 방식과 비교할 때, 다중 서비스 애플리케이션을 관리하는 데 있어 명확한 이점을 제공한다. 하지만 각자의 사용 목적과 상황에 따라 적절한 도구를 선택하는 것이 중요하다. 아래 표는 두 방식의 주요 특징과 장단점을 비교한다.

특징	단일 Docker 컨테이너 (docker run)	Docker Compose (docker compose)
관리 대상	단일 컨테이너	여러 컨테이너로 구성된 다중 서비스 애플리케이션
설정 방식	CLI 명령어(docker run)의 많은 옵션으로 설정. 스크립트화 가능.	YAML 파일(docker-compose.yml)을 통한 선언적 설정.
복잡성	단일 서비스에는 간단하지만, 다중 서비스 시 명령어 조합이 복잡해짐.	다중 서비스 설정에 최적화되어, 복잡한 환경을 명확하고 간결하게 정의.
의존성 관리	수동으로 각 컨테이너의 시작 순서 및 네트워크 연결을 관리해야 함.	depends_on을 통해 서비스 간의 의존성 및 시작 순서를 자동 관리.
환경 일관성	명령어 실행 환경에 따라 변동 가능성 존재.	docker-compose.yml 파일을 통해 모든 팀원이 동일한 환경을 구축 가능.
개발 워크플로우	각 서비스 컨테이너를 개별적으로 시작/중지/관리.	단일 명령어로 전체 애플리케이션 스택을 시작/중지/관리.
사용 사례	단일 마이크로서비스 테스트, 간단한 유틸리티 컨테이너 실행.	다중 서비스 로컬 개발 환경, 소규모 프로덕션 환경, CI/CD 테스트 환경.

위 비교에서 알 수 있듯이, 단일 Docker 컨테이너 명령어는 특정 컨테이너 하나를 빠르게 실행하고 관리하는 데 매우 효과적이다. 하지만 애플리케이션이 두 개 이상의 서비스로 구성되는 순간, 각 서비스의 의존성, 네트워크 설정, 볼륨 관리 등을 수동으로 처리하는 것은 매우 비효율적이고 오류 발생 가능성이 높다.

반면 Docker Compose는 이러한 다중 서비스 시나리오에 특화된 도구이다. docker-compose.yml 파일을 통해 전체 애플리케이션 스택을 코드로서 정의하고, 단일 명령어로 전체 스택을 제어할 수 있다. 이는 특히 로컬 개발 환경에서 빛을 발하며, 개발 팀 전체의 생산성과 환경 일관성을 보장하는 데 결정적인 역할을 수행한다.

따라서 다중 서비스 애플리케이션을 개발하고 있다면, Docker Compose의 도입은 선택이 아닌 필수적인 요소로 판단된다.

7. 결론: Docker Compose로 개발 생산성을 극대화하다

지금까지 Docker Compose를 활용하여 다중 서비스 로컬 개발 환경을 효율적으로 구축하는 방법에 대해 상세히 살펴보았다. 복잡한 마이크로서비스 아키텍처나 여러 개의 의존성을 가진 애플리케이션을 개발할 때 발생하는 환경 불일치, 설정의 복잡성, 온보딩 비용 등의 문제점들을 Docker Compose가 어떻게 해결할 수 있는지 명확히 이해할 수 있었을 것이다.

핵심적으로, Docker Compose는 docker-compose.yml이라는 단일 파일을 통해 애플리케이션을 구성하는 모든 서비스(웹 서버, 데이터베이스, 캐시 등), 네트워크, 볼륨을 선언적으로 정의할 수 있게 한다. 이는 개발 환경 설정을 코드화(Infrastructure as Code)하여 관리하는 강력한 이점을 제공하며, docker compose up 명령 하나로 전체 개발 스택을 손쉽게 시작하고 관리할 수 있도록 돕는다. 또한, 바인드 마운트를 통한 코드 실시간 동기화, .env 파일을 통한 환경 변수 관리, 사용자 정의 네트워크를 통한 서비스 간 격리 등 다양한 고급 기능을 통해 개발 워크플로우를 최적화하고 생산성을 극대화할 수 있다.

결론적으로, Docker Compose는 현대의 복잡한 소프트웨어 개발 환경에서 개발자의 생산성을 향상시키고, 팀 간의 협업 효율성을 증대시키며, 환경 일관성을 유지하는 데 필수적인 도구로 자리매김하였다. 이 가이드를 통해 독자들이 Docker Compose를 능숙하게 활용하여 더욱 견고하고 효율적인 개발 환경을 구축하고, 핵심 개발에만 집중할 수 있기를 기대한다.

본 가이드에서 다룬 내용을 바탕으로 여러분의 로컬 개발 환경을 직접 구축해보는 것을 권장한다. 혹시 Docker Compose 활용 중 겪었던 특별한 경험이나 유용한 팁이 있다면, 댓글로 공유하여 다른 개발자들과 함께 지식을 나누는 것은 어떨까?

📌 함께 읽으면 좋은 글

• [튜토리얼] Next.js 프로젝트에 TypeScript, ESLint, Prettier 완벽 설정 가이드
• [튜토리얼] Nginx 리버스 프록시 설정 완벽 가이드: 핵심 원리부터 실제 적용까지
• [보안] DevSecOps를 위한 CI/CD 파이프라인에 보안 테스트 자동화 통합 전략: 직접 써보니

이 글이 도움이 되셨다면 공감(♥)과 댓글로 응원해 주세요!
궁금한 점이나 다루었으면 하는 주제가 있다면 댓글로 남겨주세요.