튜토리얼

Docker Compose 로컬 개발 환경 구축 및 관리 가이드: 효율적인 컨테이너 활용 전략

강코의 코딩 일기 2026. 5. 27. 14:10
반응형

Docker Compose를 활용하여 복잡한 로컬 개발 환경을 효율적으로 구축하고 관리하는 방법을 상세히 안내합니다. 다중 컨테이너 애플리케이션 설정을 간소화하고 개발 생산성을 극대화하는 전략을 탐색해 보세요.

📑 목차

Docker Compose를 활용한 로컬 개발 환경 구축 및 관리 가이드 - belgium, antwerp, shipping, container, freight, cargo, transport, harbor, container, container, container, freight, cargo, cargo, cargo, cargo, cargo

Image by 2427999 on Pixabay

도입: 왜 로컬 개발 환경에 Docker Compose가 필요한가?

개발자라면 누구나 한 번쯤 로컬 개발 환경 설정의 복잡성에 직면했을 것입니다. 운영체제마다 다른 의존성 관리, 버전 충돌, 재현 불가능한 환경 문제 등은 개발 생산성을 저해하는 주된 요인으로 지목됩니다. 전통적인 방식으로는 각 개발자가 개별적으로 데이터베이스, 웹 서버, 캐시 서버 등 다양한 미들웨어를 설치하고 구성해야 하므로, 환경 설정에 소요되는 시간이 길고, 개발 환경 간 일관성을 유지하기 어렵습니다.

이러한 문제에 대한 강력한 해결책으로 컨테이너 기술이 부상하였으며, 그 중심에 Docker가 있습니다. Docker는 애플리케이션과 그 종속성을 컨테이너라는 독립적인 패키지로 묶어, 어떤 환경에서든 일관되게 실행될 수 있도록 돕습니다. 그러나 실제 애플리케이션은 단일 컨테이너로 구성되는 경우가 드뭅니다. 대부분의 현대 웹 애플리케이션은 웹 서버, 애플리케이션 서버, 데이터베이스, 캐시 서버 등 여러 개의 서비스로 이루어진 다중 컨테이너 아키텍처를 가집니다.

여기서 Docker Compose의 필요성이 대두됩니다. Docker Compose는 여러 Docker 컨테이너를 정의하고 실행하기 위한 도구입니다. 단일 YAML 파일을 사용하여 애플리케이션의 모든 서비스를 한 번에 구성하고 실행할 수 있도록 지원함으로써, 복잡한 다중 컨테이너 환경을 효율적으로 관리할 수 있게 합니다. 이는 개발 환경 설정의 번거로움을 크게 줄이고, 팀 전체의 개발 환경 일관성을 확보하는 데 결정적인 역할을 수행합니다.

본 가이드에서는 Docker Compose를 활용하여 로컬 개발 환경을 구축하고 관리하는 심층적인 방법을 다룹니다. 이를 통해 개발자는 환경 설정에 드는 시간을 최소화하고, 핵심적인 개발 업무에 집중하여 생산성을 극대화할 수 있을 것입니다.

Docker Compose 핵심 개념 이해

Docker Compose를 효과적으로 활용하기 위해서는 몇 가지 핵심 개념을 명확히 이해해야 합니다. 이 개념들은 docker-compose.yml 파일의 구조와 직접적으로 연결되며, 다중 컨테이너 애플리케이션을 정의하는 데 필수적입니다.

1. docker-compose.yml 파일

docker-compose.yml 파일은 Docker Compose 애플리케이션의 모든 구성을 정의하는 YAML 형식의 파일입니다. 이 파일은 애플리케이션을 구성하는 서비스, 네트워크, 볼륨 등을 선언합니다. 주요 최상위 키는 다음과 같습니다:

  • version: Compose 파일 형식의 버전을 명시합니다. 최신 기능 활용을 위해 가능한 한 최신 버전을 사용하는 것이 권장됩니다.
  • services: 애플리케이션을 구성하는 각 컨테이너 서비스를 정의합니다. 각 서비스는 독립적인 컨테이너로 실행됩니다.
  • networks: 서비스 간 통신을 위한 네트워크를 정의합니다.
  • volumes: 컨테이너의 데이터를 영구적으로 저장하기 위한 볼륨을 정의합니다.
  • configs, secrets: 민감한 정보나 설정 파일을 안전하게 관리하는 데 사용됩니다.

2. 서비스 (Services)

services 섹션은 애플리케이션을 구성하는 핵심 요소입니다. 각 서비스는 독립적인 컨테이너 인스턴스로 실행되며, 다음과 같은 속성들을 가질 수 있습니다:

  • image: 컨테이너를 생성할 Docker 이미지의 이름을 지정합니다 (예: nginx:latest, mysql:8.0).
  • build: Dockerfile을 사용하여 이미지를 직접 빌드할 경우, Dockerfile의 경로를 지정합니다.
  • ports: 호스트와 컨테이너 간의 포트 매핑을 정의합니다 (예: "80:80").
  • volumes: 호스트와 컨테이너 간의 볼륨 마운트를 정의합니다. 데이터를 영구적으로 저장하거나 코드 동기화를 위해 사용됩니다.
  • environment: 컨테이너 내부에서 사용할 환경 변수를 설정합니다.
  • depends_on: 서비스 간의 의존성을 선언합니다. 이는 서비스 시작 순서를 보장하는 데 유용합니다.
  • networks: 서비스가 연결될 네트워크를 지정합니다.

3. 네트워크 (Networks)

Docker Compose는 기본적으로 애플리케이션 내의 모든 서비스를 연결하는 기본 네트워크를 생성합니다. 이 네트워크를 통해 서비스들은 서로의 서비스 이름을 사용하여 통신할 수 있습니다. 예를 들어, 웹 서비스가 db라는 이름의 데이터베이스 서비스에 연결하려면, 호스트 이름으로 db를 사용하면 됩니다. 필요한 경우, 여러 개의 사용자 정의 네트워크를 생성하여 서비스 간의 격리를 구현할 수도 있습니다.

4. 볼륨 (Volumes)

컨테이너는 기본적으로 휘발성입니다. 컨테이너가 삭제되면 그 안에 저장된 데이터도 함께 사라집니다. 볼륨은 이러한 문제점을 해결하여 컨테이너의 데이터를 영구적으로 저장할 수 있도록 돕습니다. Docker Compose에서 볼륨을 사용하는 주요 목적은 다음과 같습니다:

  • 데이터 영속성: 데이터베이스와 같이 중요한 데이터를 컨테이너 외부(호스트)에 저장하여, 컨테이너가 삭제되더라도 데이터가 보존되도록 합니다.
  • 코드 동기화: 호스트 머신의 소스 코드를 컨테이너 내부로 마운트하여, 호스트에서 코드를 수정하면 컨테이너 내부에서 즉시 반영되도록 합니다. 이는 개발 과정에서 매우 유용합니다.

볼륨은 명명된 볼륨(named volumes)과 바인드 마운트(bind mounts) 두 가지 방식으로 주로 사용됩니다.

다음은 Docker Compose 파일의 간략한 예시입니다:


version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./html:/usr/share/nginx/html
    depends_on:
      - app
  app:
    build: .
    volumes:
      - .:/app
    environment:
      DATABASE_URL: postgres://user:password@db:5432/mydatabase
    depends_on:
      - db
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

이 예시에서는 web, app, db 세 가지 서비스가 정의되어 있습니다. web 서비스는 Nginx 웹 서버를, app 서비스는 Dockerfile을 통해 빌드된 애플리케이션을, db 서비스는 PostgreSQL 데이터베이스를 나타냅니다. db_data라는 명명된 볼륨을 사용하여 데이터베이스 데이터를 영구적으로 저장하고 있으며, 서비스들은 서로 의존성을 가지고 네트워크를 통해 통신합니다.

로컬 개발 환경 구축 시작하기: 기본 설정

Docker Compose를 활용한 로컬 개발 환경 구축의 첫 단계는 필요한 도구를 설치하고, 간단한 애플리케이션 스택을 구성하는 것입니다. 여기서는 일반적인 웹 애플리케이션 스택(예: Nginx, Node.js 애플리케이션, PostgreSQL)을 예시로 들어 설명합니다.

1. 필수 도구 설치

Docker Compose를 사용하려면 Docker Desktop이 설치되어 있어야 합니다. Docker Desktop은 Docker Engine, Docker CLI, Docker Compose를 포함하고 있어, 개발 환경 구축에 필요한 모든 기능을 제공합니다. macOS, Windows, Linux 등 다양한 운영체제에서 사용 가능합니다.

설치 후 터미널에서 다음 명령어를 실행하여 Docker와 Docker Compose가 올바르게 설치되었는지 확인할 수 있습니다:


docker --version
docker compose version

2. 프로젝트 디렉토리 구조 설정

새로운 프로젝트 디렉토리를 생성하고, 그 안에 docker-compose.yml 파일을 비롯한 필요한 파일들을 배치합니다. 일반적인 구조는 다음과 같습니다:


my-app/
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── index.js
│   └── package.json
└── frontend/
    ├── Dockerfile
    ├── index.html
    ├── script.js
    └── style.css

3. docker-compose.yml 파일 작성 예시

다음은 Node.js 백엔드, Nginx 프록시, PostgreSQL 데이터베이스로 구성된 기본적인 웹 애플리케이션 스택을 위한 docker-compose.yml 파일입니다.


# docker-compose.yml
version: '3.8'

services:
  # 1. PostgreSQL 데이터베이스 서비스
  db:
    image: postgres:14-alpine # 경량 PostgreSQL 이미지 사용
    container_name: myapp_db
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password123
    volumes:
      - db_data:/var/lib/postgresql/data # 데이터 영속성을 위한 명명된 볼륨
    ports:
      - "5432:5432" # 로컬에서 DB 접속을 위한 포트 포워딩 (선택 사항)
    restart: always # 컨테이너 비정상 종료 시 항상 재시작

  # 2. Node.js 백엔드 애플리케이션 서비스
  backend:
    build: ./backend # backend 디렉토리의 Dockerfile을 사용하여 이미지 빌드
    container_name: myapp_backend
    ports:
      - "3000:3000" # 로컬 호스트 3000번 포트와 컨테이너 3000번 포트 매핑
    volumes:
      - ./backend:/app # 호스트의 backend 코드를 컨테이너의 /app으로 마운트 (코드 동기화)
      - /app/node_modules # node_modules는 볼륨 마운트에서 제외 (컨테이너 내부에 유지)
    environment:
      DATABASE_URL: postgres://user:password123@db:5432/mydatabase # DB 연결 정보
      NODE_ENV: development
    depends_on:
      - db # db 서비스가 먼저 시작되도록 의존성 설정
    restart: on-failure # 컨테이너 비정상 종료 시 재시작

  # 3. Nginx 웹 서버 (프록시) 서비스
  nginx:
    image: nginx:stable-alpine # 경량 Nginx 이미지 사용
    container_name: myapp_nginx
    ports:
      - "80:80" # 웹 애플리케이션 접근을 위한 80번 포트 포워딩
      - "443:443" # HTTPS를 위한 443번 포트 포워딩 (필요시)
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro # Nginx 설정 파일 마운트 (읽기 전용)
      - ./nginx/conf.d:/etc/nginx/conf.d:ro # Nginx 추가 설정 파일 마운트
      - ./frontend:/usr/share/nginx/html:ro # 정적 프론트엔드 파일 마운트
    depends_on:
      - backend # backend 서비스가 먼저 시작되도록 의존성 설정
    restart: always

# 명명된 볼륨 정의
volumes:
  db_data: # db 서비스에서 사용될 데이터 볼륨

이 파일은 세 가지 주요 서비스를 정의합니다:

  • db (PostgreSQL): 데이터베이스 역할을 수행합니다. db_data 볼륨을 사용하여 데이터를 영구적으로 저장합니다.
  • backend (Node.js): 실제 애플리케이션 로직을 처리하는 백엔드 서비스입니다. ./backend 디렉토리의 Dockerfile을 사용하여 이미지를 빌드하고, 호스트의 코드를 컨테이너로 마운트하여 실시간 개발을 가능하게 합니다. db 서비스에 의존합니다.
  • nginx (Nginx): 정적 파일 서빙 및 backend 서비스로의 리버스 프록시 역할을 수행합니다. ./nginx 디렉토리의 설정 파일을 마운트하고, ./frontend 디렉토리의 정적 프론트엔드 파일을 서빙합니다. backend 서비스에 의존합니다.

4. 서비스별 Dockerfile 및 설정 파일 준비

docker-compose.yml 파일에서 참조하는 Dockerfile과 설정 파일들을 준비해야 합니다.

backend/Dockerfile 예시:


# backend/Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["node", "index.js"]

backend/index.js 예시:


// backend/index.js
const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello from Backend!');
});

app.listen(port, () => {
  console.log(`Backend listening on port ${port}`);
});

backend/package.json 예시:


// backend/package.json
{
  "name": "backend",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.18.2",
    "pg": "^8.11.3"
  }
}

nginx/nginx.conf 예시:


# nginx/nginx.conf
user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    include /etc/nginx/conf.d/*.conf; # conf.d 디렉토리의 모든 .conf 파일 포함
}

nginx/conf.d/default.conf 예시:


# nginx/conf.d/default.conf
server {
    listen 80;
    server_name localhost;

    location / {
        root   /usr/share/nginx/html; # 정적 파일 경로
        index  index.html index.htm;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://backend:3000/; # backend 서비스로 요청 프록시
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

frontend/index.html 예시:


<!-- frontend/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Docker Compose App</title>
</head>
<body>
    <h1>Welcome to My App!</h1>
    <p>This is the frontend served by Nginx.</p>
    <button onclick="fetchBackend()">Fetch Backend</button>
    <p id="backend-response"></p>

    <script>
        async function fetchBackend() {
            try {
                const response = await fetch('/api/');
                const text = await response.text();
                document.getElementById('backend-response').innerText = `Backend says: ${text}`;
            } catch (error) {
                document.getElementById('backend-response').innerText = `Error: ${error.message}`;
            }
        }
    </script>
</body>
</html>

5. 환경 실행

모든 파일 준비가 완료되면, 프로젝트 루트 디렉토리에서 다음 명령어를 실행하여 서비스를 빌드하고 시작할 수 있습니다:


docker compose up --build -d
  • up: docker-compose.yml 파일에 정의된 모든 서비스를 시작합니다.
  • --build: 서비스에 대한 이미지가 없거나 변경 사항이 있을 경우, 이미지를 다시 빌드합니다.
  • -d: 서비스를 백그라운드(detached mode)에서 실행합니다.

서비스가 성공적으로 실행되면, 웹 브라우저에서 http://localhost에 접속하여 Nginx가 서빙하는 프론트엔드 페이지를 확인할 수 있습니다. "Fetch Backend" 버튼을 클릭하면 Nginx를 통해 백엔드 서비스로부터 응답을 받아올 것입니다.

Docker Compose를 활용한 로컬 개발 환경 구축 및 관리 가이드 - the bottle, plastic, segregation, processing, recycling, reflection, container, waste, garbage, responsibility, throw, blue, services, pollution, empty, shine, wet, problem, to treat with, transparent, plastic waste, earth day, plastic, plastic, plastic, plastic, plastic, recycling, waste, plastic waste

Image by pasja1000 on Pixabay

다중 서비스 및 데이터 관리 전략

복잡한 애플리케이션에서는 여러 서비스 간의 효율적인 통신과 데이터의 안정적인 관리가 중요합니다. Docker Compose는 이러한 요구 사항을 충족하기 위한 강력한 기능을 제공합니다.

1. 서비스 간 통신

Docker Compose는 기본적으로 모든 서비스를 단일 네트워크에 연결합니다. 이 네트워크 내에서 서비스들은 서로의 서비스 이름을 사용하여 통신할 수 있습니다. 별도의 IP 주소를 알 필요 없이, docker-compose.yml 파일에 정의된 서비스 이름을 호스트 이름처럼 사용할 수 있습니다.


# 예시: backend 서비스에서 db 서비스로 연결
# backend/index.js (또는 환경변수)
const dbHost = process.env.DATABASE_URL || 'db'; // 'db'는 docker-compose.yml에 정의된 서비스 이름
const dbPort = 5432;
// ...

이러한 방식은 개발자가 서비스 간의 네트워크 구성에 대해 깊이 고민할 필요 없이, 논리적인 서비스 이름만으로 상호작용할 수 있도록 하여 개발 편의성을 크게 높입니다.

2. 데이터 영속성을 위한 볼륨 관리

앞서 언급했듯이, 컨테이너는 휘발성이므로 중요한 데이터를 영구적으로 저장하기 위해 볼륨을 사용해야 합니다. 주로 데이터베이스 데이터를 보존하는 데 활용됩니다.

  • 명명된 볼륨 (Named Volumes): Docker가 관리하는 호스트 파일 시스템의 특정 위치에 데이터를 저장합니다. 이 방법은 컨테이너가 삭제되어도 데이터가 손실되지 않으며, 여러 컨테이너가 동일한 데이터를 공유할 수 있게 합니다.
  • 바인드 마운트 (Bind Mounts): 호스트 머신의 특정 디렉토리나 파일을 컨테이너 내부의 경로에 직접 마운트합니다. 개발 중 소스 코드 변경 사항을 즉시 컨테이너에 반영해야 할 때 유용합니다.

볼륨 비교: 명명된 볼륨 vs. 바인드 마운트

특징 명명된 볼륨 (Named Volumes) 바인드 마운트 (Bind Mounts)
관리 주체 Docker Engine이 관리 사용자가 호스트 파일 시스템의 경로 지정
데이터 영속성 높음 (컨테이너 삭제 시에도 데이터 보존) 호스트 파일 시스템에 직접 저장되므로 보존
사용 사례 데이터베이스 데이터, 캐시 등 애플리케이션 데이터 소스 코드, 설정 파일, 빌드 아티팩트 등 개발 중 변경될 수 있는 파일
성능 일반적으로 바인드 마운트보다 빠를 수 있음 (특히 Docker Desktop 환경) 호스트 파일 시스템의 I/O 성능에 직접 영향 받음
이식성 높음 (Docker가 경로 관리, 호스트 경로에 독립적) 낮음 (호스트의 특정 경로에 의존)

개발 환경에서는 소스 코드 동기화를 위해 바인드 마운트를, 데이터베이스 데이터와 같이 중요한 영속성 데이터를 위해서는 명명된 볼륨을 함께 사용하는 것이 일반적인 전략입니다.

3. 환경 변수 활용

환경 변수는 컨테이너 내부에서 애플리케이션 설정을 동적으로 변경하는 데 사용됩니다. 데이터베이스 연결 정보, API 키, 개발/운영 모드 전환 등 다양한 용도로 활용됩니다. Docker Compose는 environment 키를 통해 직접 환경 변수를 설정하거나, .env 파일을 통해 관리할 수 있습니다.

  • environment 키 사용: docker-compose.yml 내에 직접 명시합니다. 
    
services:
  backend:
    environment:
      DATABASE_URL: postgres://user:password@db:5432/mydatabase
      NODE_ENV: development
  • .env 파일 사용: 민감한 정보나 환경별로 달라지는 값을 관리할 때 유용합니다. 프로젝트 루트 디렉토리에 .env 파일을 생성하고, docker-compose.yml에서 ${VARIABLE_NAME} 형식으로 참조할 수 있습니다. .env 파일은 버전 관리 시스템에 포함하지 않는 것이 일반적입니다. 
    
# .env 파일
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword
DB_NAME=mydb

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

개발 워크플로우 최적화: 유용한 명령어와 팁

Docker Compose는 로컬 개발 환경 관리를 위한 다양한 CLI 명령어를 제공합니다. 이 명령어를 숙지하면 개발 워크플로우를 크게 효율화할 수 있습니다.

1. 핵심 Docker Compose 명령어

  • docker compose up [서비스 이름...]: 모든 서비스 또는 지정된 서비스를 시작하고, 필요한 경우 이미지를 빌드합니다.
    • docker compose up -d: 서비스를 백그라운드에서 실행합니다.
    • docker compose up --build: 이미지 캐시를 무시하고 항상 새로 빌드합니다.
  • docker compose down: docker-compose.yml에 정의된 모든 서비스 컨테이너를 중지하고 삭제합니다.
    • docker compose down --volumes: 컨테이너와 함께 볼륨도 삭제합니다. 데이터베이스 데이터가 포함된 볼륨을 삭제할 때는 주의해야 합니다.
    • docker compose down --rmi all: 컨테이너와 함께 생성된 이미지도 모두 삭제합니다.
  • docker compose start [서비스 이름...]: 이전에 중지된 서비스를 다시 시작합니다.
  • docker compose stop [서비스 이름...]: 실행 중인 서비스를 중지합니다. 컨테이너는 삭제되지 않습니다.
  • docker compose restart [서비스 이름...]: 실행 중인 서비스를 재시작합니다.
  • docker compose ps: 현재 실행 중인 서비스의 상태를 보여줍니다.
  • docker compose logs [서비스 이름...]: 서비스의 로그를 출력합니다.
    • docker compose logs -f [서비스 이름...]: 실시간으로 로그를 추적합니다.
  • docker compose exec [서비스 이름] [명령어]: 실행 중인 서비스 컨테이너 내에서 명령어를 실행합니다.
    • docker compose exec backend bash: backend 컨테이너에 접속하여 bash 셸을 실행합니다.
  • docker compose build [서비스 이름...]: 서비스의 이미지를 미리 빌드합니다.

2. 개발 생산성 향상을 위한 팁

  • 자동 재시작 정책 (restart): docker-compose.yml 파일의 각 서비스에 restart 정책을 설정하여 컨테이너가 예기치 않게 종료될 경우 자동으로 재시작되도록 할 수 있습니다. always, on-failure, unless-stopped 등의 옵션이 있습니다. 개발 환경에서는 on-failure가 적절한 경우가 많습니다.
  • docker compose watch (실험적 기능): Docker Compose CLI에 포함된 watch 명령어는 호스트 파일 시스템의 변경 사항을 감지하여 자동으로 컨테이너를 업데이트하거나 재시작하는 기능을 제공합니다. 이는 개발자가 수동으로 컨테이너를 재시작하는 번거로움을 줄여줍니다. 
    
# docker-compose.yml (watch 섹션 추가)
version: '3.8'

services:
  backend:
    build: ./backend
    volumes:
      - ./backend:/app
    develop: # watch 설정
      watch:
        - path: ./backend
          action: sync # 변경 시 컨테이너로 파일 동기화
          ignore:
            - node_modules/
        - path: ./backend/Dockerfile
          action: rebuild # Dockerfile 변경 시 이미지 재빌드

    
docker compose watch
    이 기능은 특히 프론트엔드나 백엔드 코드 변경 시 즉각적인 반영이 필요할 때 매우 유용합니다.
  • 멀티 스테이지 빌드 (Multi-stage Builds): Dockerfile에서 멀티 스테이지 빌드를 사용하면 개발 환경과 프로덕션 환경 이미지를 효율적으로 관리할 수 있습니다. 개발 시에는 디버깅 도구나 큰 용량의 의존성을 포함한 이미지를 사용하고, 프로덕션 배포 시에는 최종 결과물만 포함한 경량 이미지를 생성하여 이미지 크기를 최적화할 수 있습니다.
  • 환경 변수 파일 (.env) 활용: 로컬 개발 환경과 다른 환경(예: 테스트, 스테이징) 간에 설정이 달라지는 경우, .env 파일을 통해 환경 변수를 분리하여 관리하는 것이 좋습니다. .env 파일은 .gitignore에 추가하여 버전 관리에서 제외하는 것이 일반적입니다.
  • Docker Compose Profiles: 여러 환경(예: 개발, 테스트) 또는 특정 기능(예: Prometheus 모니터링)에 따라 다른 서비스 세트를 활성화하고 싶을 때 profiles를 사용할 수 있습니다. 
    
# docker-compose.yml
services:
  app:
    # ...
  db:
    # ...
  adminer: # 관리 도구
    image: adminer
    ports:
      - "8080:8080"
    profiles:
      - debug # debug 프로파일이 활성화될 때만 실행

    
docker compose --profile debug up -d # debug 프로파일 활성화
    이를 통해 필요한 서비스만 선택적으로 실행하여 자원 사용을 최적화하고, 개발 환경의 복잡성을 줄일 수 있습니다.
Docker Compose를 활용한 로컬 개발 환경 구축 및 관리 가이드 - computer, laptop, tech, blue computer, blue laptop, blue tech, computer, laptop, tech, tech, tech, tech, tech

Image by yeiferr on Pixabay

흔히 발생하는 문제 해결 및 성능 최적화

Docker Compose를 사용하다 보면 몇 가지 일반적인 문제에 직면할 수 있습니다. 이러한 문제들을 해결하고 개발 환경의 성능을 최적화하는 방법을 이해하는 것은 중요합니다.

1. 흔히 발생하는 문제 해결

  • 포트 충돌 (Port Conflicts): 가장 흔한 문제 중 하나는 호스트 머신의 포트가 이미 다른 프로세스에 의해 사용 중일 때 발생합니다. Docker Compose는 ports 섹션에 지정된 호스트 포트를 사용하려고 시도합니다.
    • 해결책: docker-compose.yml 파일에서 호스트 포트 번호를 변경하거나, 현재 사용 중인 포트를 확인하고 해당 프로세스를 종료합니다. 
      
# 포트 변경 예시
services:
  nginx:
    ports:
      - "8080:80" # 80번 대신 8080번 포트 사용
    • 포트 사용 확인 (Linux/macOS): lsof -i :[포트번호] 또는 netstat -tulnp | grep [포트번호]
    • 포트 사용 확인 (Windows): netstat -ano | findstr :[포트번호]
  • 볼륨 권한 문제 (Volume Permissions): 리눅스 기반 컨테이너에서 호스트의 파일을 바인드 마운트할 때 권한 문제가 발생할 수 있습니다. 컨테이너 내부의 프로세스가 마운트된 디렉토리에 접근하거나 쓰기 권한이 없을 때 발생합니다.
    • 해결책:
      • 컨테이너 내부에서 파일에 접근하는 유저의 UID/GID를 호스트의 유저와 일치시킵니다. (예: Dockerfile에 USER 명령 사용)
      • 호스트 디렉토리의 권한을 컨테이너가 접근할 수 있도록 chmod 명령으로 변경합니다 (예: chmod -R 777 ./data). 단, 보안상의 이유로 777 권한은 주의해서 사용해야 합니다.
      • Docker Desktop 환경에서는 볼륨 마운트 시 권한 문제를 자동으로 처리하는 경우가 많지만, Linux 호스트에서는 명시적인 설정이 필요할 수 있습니다.
  • 서비스 시작 실패 및 로그 확인: 서비스가 제대로 시작되지 않거나 예상대로 작동하지 않을 때, 가장 먼저 해야 할 일은 로그를 확인하는 것입니다.
    • 해결책: docker compose logs [서비스 이름] 명령어를 사용하여 특정 서비스의 로그를 확인합니다. -f 옵션을 사용하면 실시간으로 로그를 추적할 수 있습니다. 로그에서 에러 메시지나 경고를 찾아 원인을 파악합니다.
  • 이미지 빌드 실패: Dockerfile에 문법 오류가 있거나, 네트워크 문제로 의존성 패키지를 다운로드하지 못할 때 빌드가 실패할 수 있습니다.
    • 해결책: 빌드 로그를 자세히 확인하여 어느 단계에서 실패했는지 파악합니다. Dockerfile의 각 명령어가 독립적으로 실행되므로, 실패한 지점을 찾기 쉽습니다. 네트워크 문제의 경우, 인터넷 연결 상태를 확인하거나 Docker 데몬의 DNS 설정을 점검합니다.

2. 성능 최적화 전략

로컬 개발 환경에서 Docker Compose의 성능을 최적화하면 개발 경험을 크게 향상시킬 수 있습니다.

  • Docker Desktop 리소스 할당 최적화: Docker Desktop은 기본적으로 일정량의 CPU, 메모리, 디스크 공간을 가상 머신에 할당합니다. 프로젝트의 규모와 워크로드에 따라 이 리소스를 적절히 조절해야 합니다.
    • 조정 방법: Docker Desktop 설정(Preferences/Settings)에서 Resources 탭을 통해 CPU 코어 수, 메모리, 스왑 공간 등을 조정할 수 있습니다. 과도하게 할당하면 호스트 머신이 느려질 수 있고, 부족하게 할당하면 컨테이너 성능이 저하될 수 있으므로 균형을 찾는 것이 중요합니다.
  • 볼륨 마운트 성능 고려: 특히 macOS 및 Windows의 Docker Desktop 환경에서는 바인드 마운트의 I/O 성능이 Linux 호스트에 비해 떨어질 수 있습니다. 이는 호스트 파일 시스템과 Docker 가상 머신 간의 동기화 오버헤드 때문입니다.
    • 최적화 방법:
      • 자주 변경되지 않는 파일(예: node_modules, 캐시 디렉토리)은 컨테이너 내부에 두거나 명명된 볼륨을 사용합니다. .dockerignore 파일을 사용하여 불필요한 파일을 이미지 빌드 시 제외하고, 바인드 마운트에서 특정 경로를 제외할 수 있습니다 (volumes: - /app/node_modules).
      • Docker Desktop의 "VirtioFS"나 "gRPC FUSE"와 같은 파일 시스템 공유 기술을 활용하여 성능을 개선합니다.
  • 이미지 크기 최소화: 작은 이미지일수록 빌드 및 다운로드 시간이 단축되고, 컨테이너 시작 속도가 빨라집니다.
    • 최적화 방법:
      • 경량 베이스 이미지 사용 (예: alpine 버전).
      • 멀티 스테이지 빌드를 사용하여 최종 이미지에 필요한 최소한의 파일만 포함합니다.
      • .dockerignore 파일을 활용하여 불필요한 파일을 이미지에 포함하지 않습니다.
      • RUN 명령을 체이닝하여 레이어 수를 줄입니다.
  • 로깅 수준 조정: 너무 많은 로그 출력은 디스크 I/O를 증가시키고, 로그 파일을 분석하기 어렵게 만듭니다.
      • 최적화 방법: 개발 중에는 상세한 로그가 필요할 수 있지만, 필요한 경우 애플리케이션의 로깅 수준을 조정하여 불필요한 로그를 줄일 수 있습니다. docker-compose.yml의 logging 드라이버를 사용하여 로그 관리 정책을 설정할 수도 있습니다.
    
services:
  backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

결론: Docker Compose와 함께하는 효율적인 개발의 미래

지금까지 Docker Compose를 활용하여 로컬 개발 환경을 구축하고 관리하는 다양한 방법을 살펴보았습니다. Docker Compose는 다중 컨테이너 애플리케이션의 복잡성을 효과적으로 관리하고, 개발 환경의 일관성과 재현성을 보장하는 데 핵심적인 도구입니다.

핵심적으로, docker-compose.yml 파일을 통해 서비스, 네트워크, 볼륨을 명확하게 정의함으로써, 개발자는 단일 명령어로 전체 애플리케이션 스택을 손쉽게 시작하고 중지할 수 있습니다. 이는 새로운 팀원이 프로젝트에 합류하거나, 기존 프로젝트를 다른 개발 환경에서 설정해야 할 때 발생하는 시간과 노력을 획기적으로 절감합니다. 또한, 코드 변경 사항을 즉시 반영하는 바인드 마운트, 데이터 영속성을 위한 명명된 볼륨, 유연한 환경 변수 관리 등의 기능은 개발 생산성을 극대화하는 데 기여합니다.

흔히 발생하는 포트 충돌이나 권한 문제에 대한 해결책과 Docker Desktop 리소스 할당, 볼륨 마운트 성능 최적화 등은 안정적이고 빠른 개발 경험을 위한 필수적인 지식입니다. docker compose watch와 같은 새로운 기능들은 개발자의 워크플로우를 더욱 간소화하고, 피드백 루프를 단축하여 효율성을 높여줍니다.

결론적으로, Docker Compose는 현대적인 애플리케이션 개발 환경에서 필수적인 역량으로 자리매김하고 있습니다. 이 가이드를 통해 얻은 지식을 바탕으로 여러분의 로컬 개발 환경을 더욱 강력하고 효율적으로 구축하고 관리할 수 있기를 바랍니다. 복잡한 환경 설정에 시간을 낭비하는 대신, 핵심적인 개발 작업에 집중하여 더 나은 소프트웨어를 만드는 데 기여할 수 있을 것입니다.

Docker Compose를 활용한 로컬 개발 환경 구축에 대한 여러분의 경험이나 추가적인 팁이 있다면 댓글로 공유해 주세요. 함께 더 나은 개발 문화를 만들어 나갈 수 있습니다.

📌 함께 읽으면 좋은 글

  • [생산성 자동화] 개발 워크플로우 최적화: 커스텀 CLI 도구와 자동화 스크립트 개발 가이드
  • [개발 도구] CI/CD 파이프라인 구축: GitHub Actions와 GitLab CI 심층 비교 가이드
  • [튜토리얼] Go 언어 RESTful API 서버 구축: Gin 프레임워크 실전 가이드

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

반응형

'튜토리얼' 카테고리의 다른 글

Kafka를 활용한 분산 메시지 큐 시스템 구축 실전 가이드  (0) 2026.05.30
Go 언어와 Fiber 프레임워크로 빠르고 견고한 RESTful API 서버 구축하기  (0) 2026.05.28
Vite와 TypeScript로 React 개발 환경 구축하기: 빠르고 효율적인 프론트엔드 최적화 가이드  (0) 2026.05.27
Go 언어 RESTful API 서버 구축: Gin 프레임워크 실전 가이드  (0) 2026.05.26
Docker Compose 활용 다중 컨테이너 애플리케이션 개발 환경 구축 상세 가이드  (0) 2026.05.25

'튜토리얼'의 다른글

  • 현재글Docker Compose 로컬 개발 환경 구축 및 관리 가이드: 효율적인 컨테이너 활용 전략

관련글

티스토리툴바