Docker Compose로 개발 환경 통합한 후 실제 겪은 문제와 해결법

처음에 Docker Compose로 개발 환경을 통합하려고 할 때, 생각보다 삽질이 많았어요. 여러 컨테이너를 한꺼번에 띄우고 서로 연결하는 과정에서 네트워크 문제도 있고, 볼륨 마운트 설정부터 환경 변수 관리까지 꼬이는 게 한두 가지가 아니더라고요.

이 글에서는 제가 Docker Compose로 실제 개발 환경을 구축하면서 마주친 문제들, 어떻게 해결했는지 그리고 다른 사람들 사례와 비교한 내용까지 꼼꼼히 정리했어요. 특히, A상품과 B상품이라 볼 수 있는 Docker Compose와 다른 툴(예: Kubernetes, Docker Swarm) 간 장단점도 표로 정리해두었습니다.

개발 환경 / 버전 정보

제가 사용한 버전은 Docker 24.0.2와 Docker Compose 2.21.0입니다. OS는 macOS Ventura 13.4를 사용했고, 기본적으로 Node.js와 MySQL 컨테이너를 조합해 서비스 개발 환경을 만들었어요.

Docker Compose로 개발 환경 통합한 후기 관련 정보

Docker Compose 핵심 세팅과 직접 쓴 예시

사실 이 부분이 제일 중요했는데요, docker-compose.yml 파일을 통해 여러 컨테이너를 한 번에 띄우는 게 기본 목표였어요. 아래는 제가 쓴 예시 코드입니다. Node.js 앱과 MySQL DB를 연결하는 구성이에요.

version: '3.9'

services:
  app:
    image: node:18
    working_dir: /usr/src/app
    volumes:
      - ./:/usr/src/app
      - /usr/src/app/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - DB_HOST=db
      - DB_USER=root
      - DB_PASS=example
    command: sh -c "npm install && npm run dev"

  db:
    image: mysql:8.0
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: example
      MYSQL_DATABASE: testdb
    volumes:
      - db-data:/var/lib/mysql
    ports:
      - "3306:3306"

volumes:
  db-data:

위 설정은 간단해 보이지만, 여기서 제가 겪은 중요한 포인트는 볼륨 마운트 문제였어요. 특히 Mac 환경에서 node_modules를 그냥 소스코드와 함께 마운트하면 퍼포먼스가 심각하게 떨어지더라고요. 그래서 빈 볼륨을 따로 마운트해서 그 문제를 해결했어요.

여기서 많이 틀립니다: 네트워크와 환경 변수 관리

그런데 여기서 사람들이 많이 헷갈려하는 부분이 네트워크 설정과 환경 변수 범위였어요. 저는 처음에 DB 컨테이너 이름을 잘못 참조해서 연결 실패 난 적이 있거든요. Compose 기본 네트워크가 서비스명 기준으로 DNS를 제공하는데, 이걸 모르면 localhost나 127.0.0.1로 연결하려다 실패합니다.

그리고 환경 변수 관리도 복잡해요. 저는 .env 파일을 따로 만들어서 Compose가 자동으로 읽게 했는데, 가끔 환경 변수 충돌이나 미설정으로 인한 에러가 나서 엄청 헤맸습니다.

Docker Compose로 개발 환경 통합한 후기 관련 정보

다른 사람들은 이렇게 했다: Kubernetes, Docker Swarm과 비교

제가 Docker Compose를 쓰면서 느낀 점과 주변 동료들이 쓴 Kubernetes, Docker Swarm과 비교해 보면, 서비스 규모나 복잡도에 따라 확실히 선택지가 달라지더라고요. 아래 표로 정리했어요.

특징	Docker Compose	Kubernetes	Docker Swarm
복잡도	낮음, 단일 호스트 최적	높음, 클러스터 관리 필수	중간, 간단한 클러스터링 가능
학습 곡선	완만함	가파름	중간
서비스 확장성	제한적	매우 높음	높음
공동 개발 환경 용이성	가장 쉬움	복잡	보통
설정 및 디버깅	간단하고 빠름	복잡, 로그 확인 어려움	중간

요약하자면, 작은 프로젝트나 단순한 개발 환경은 Docker Compose가 그냥 최고라는 거예요. 복잡한 프로덕션 환경이나 대규모 서비스는 Kubernetes가 필수고, 그 중간 단계에서는 Docker Swarm도 괜찮습니다.

실제로 겪은 문제와 해결법

제일 크게 막혔던 건 바로 컨테이너 간 네트워크 이름 해석 문제였어요. 처음에 DB 컨테이너 IP를 직접 하드코딩했다가, IP가 바뀌면서 매번 연결 실패가 났죠. Compose는 자체 DNS 서비스를 제공하는데, 그걸 몰라서 굉장히 헤맸어요.

또 한 가지는 볼륨과 권한 문제였어요. 윈도우나 맥에서 호스트와 컨테이너 간 파일 공유할 때 권한 문제로 파일이 안 읽히거나 쓸 수 없었는데, 아래 설정을 추가해서 겨우 해결했네요.

services:
  app:
    volumes:
      - ./:/usr/src/app:delegated

위 :delegated 옵션은 마운트 성능과 권한 문제에 도움을 줘요. 특히 Mac에서 쓰면 속도가 눈에 띄게 빨라집니다.

Docker Compose로 개발 환경 통합한 후기 관련 정보

심화: 자동화와 확장 용이성까지 생각하기

그리고 저는 Compose 파일을 여러 개로 쪼개서 기본 설정과 개발 전용 설정을 분리해봤어요. 이렇게 하면 dev/prod 환경을 관리하기 더 편하더라고요.

예를 들어, docker-compose.yml과 docker-compose.override.yml 을 같이 쓴 거예요. 이렇게 하면 기본설정은 유지하고 개발환경에 특화된 설정만 덧붙일 수 있어서 편리합니다.

자주 물어보시는 것들

Q. Docker Compose에서 컨테이너 간 통신이 안 될 때 어떻게 해야 하나요?

A. 보통 서비스 이름으로 연결해야 합니다. 예를 들어 DB 컨테이너 이름이 db라면 앱에서는 호스트를 db로 지정해야 해요. localhost나 IP 직접 입력은 피하세요.

Q. 로컬 파일 변경 사항이 컨테이너에 바로 반영 안 될 때 어떻게 하나요?

A. 볼륨 마운트 옵션에 :delegated 나 :cached를 붙이면 성능이 개선됩니다. 맥, 윈도우 환경에서 특히 효과적이에요.

제 경험을 토대로 Docker Compose로 개발 환경 통합하는 건 작고 단순한 팀에 딱 맞는 솔루션이라고 생각돼요. 물론 대규모 서비스라면 Kubernetes 쪽으로 가는 게 맞지만, 여러 서비스 띄우고 파일 공유하며 환경 변수 관리하는 기본기는 여기서 충분히 익힐 수 있거든요. 다음에는 Kubernetes로 확장하는 경험도 정리해볼게요.

📌 함께 보면 좋은 글

• SSH 키 관리 실수로 서버 잠긴 경험과 실전 해결법 공유
• Linux 명령어, 인프라 초보도 매일 쓰는 실무 필수 정리법
• 2026년 Linux 메모리 부족 원인 추적하면서 알게 된 변화와 팁