Docker Compose로 개발 환경 통합할 때 제가 겪은 문제와 해결법

사실 이걸 세팅하다가 생각보다 삽질을 많이 했어요. 여러 개 컨테이너를 통합하려니 네트워크, 볼륨, 환경변수 때문에 헷갈리는 부분이 한두 군데가 아니더라고요.

이 글에서는 제가 직접 Docker Compose로 여러 서비스를 묶어서 개발 환경을 만들면서 자주 만난 문제, 그리고 구체적인 명령어와 설정값을 정리했어요. Q&A 형식으로 궁금한 점을 바로바로 해결할 수 있게 했으니 꼭 끝까지 읽어보시면 좋겠네요.

개발 환경 / 버전 정보

제가 사용한 도구 버전은 다음과 같아요. Docker 24.0.5, Docker Compose V2, Ubuntu 22.04 LTS 환경입니다. 이 조합에서 실습했어요.

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

Docker Compose 기본 구조 이렇게 하면 됩니다

처음에 제가 만든 docker-compose.yml 파일은 웹과 DB 컨테이너를 함께 띄우는 기본 형태였어요. 설정은 꽤 직관적이었는데 시크릿, 네트워크 문제 때문에 한참 헤맸죠.

version: '3.9'
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example
    volumes:
      - db_data:/var/lib/mysql
volumes:
  db_data:

이렇게 하면 웹과 데이터베이스가 기본 볼륨과 포트 매핑으로 동작했어요. 하지만 이 상태로는 개발 환경 통합에 부족한 점이 있었답니다.

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

자주 물어보시는 것들

Q. 컨테이너 간 네트워크 연결이 안 될 때 왜 그럴까요?

A. Docker Compose는 기본적으로 같은 프로젝트 안의 서비스끼리 같은 기본 네트워크를 사용해요. 근데 제가 특정 컨테이너를 별도 네트워크에 연결하거나 외부 네트워크를 써서 네트워크 분리했을 때 연결이 안 된 적 있었죠. 그럴 땐
networks 설정을 명확히 지정해주고, 각 서비스에 연결할 네트워크 이름을 넣는 게 중요해요.

version: '3.9'
services:
  app:
    image: myapp:latest
    networks:
      - front_net
  db:
    image: mysql:8.0
    networks:
      - back_net
networks:
  front_net:
  back_net:

이렇게 분리하고 싶을 때는 네트워크 별로 정의하고, 서비스에 직접 붙여야 해요. 아니면 기본 네트워크만 쓸 때는 아예 네트워크를 정의하지 않아도 됩니다.

Q. 환경변수를 여러 컨테이너에 동일하게 적용하고 싶어요. 제일 좋은 방법은?

A. 저는 보통 .env 파일을 만들어서 쓰거든요. Docker Compose가 자동으로 읽어 주니까 편해요.
예를 들어 .env 파일에 MYSQL_ROOT_PASSWORD=example 이렇게 적고, docker-compose.yml 에서는 별도 입력 없이 ${MYSQL_ROOT_PASSWORD} 이렇게 써서 참조하면 돼요.

저도 처음엔 여러 곳에 중복 입력하다가 나중에 한 곳에서 관리하는 게 훨씬 편하다는 걸 깨달았어요.

Q. 볼륨 마운트가 작동 안 할 때, 특히 로컬 폴더와 연동 문제는 왜 그런 건가요?

A. 가장 많이 겪는 문제 중 하나인데, 경로 지정 실수가 많아요. 도커 컴포즈 파일 내 경로는 compose 파일 위치 기준이거든요. 제가 실수로 절대경로랑 상대경로를 섞어서 지정했는데 그때 마운트가 누락되더라고요.
예를 들어 ./html:/usr/share/nginx/html:ro 는 compose 파일 기준으로 로컬 'html' 폴더가 있어야 합니다. 없다면 마운트가 안 되니 꼭 확인하세요.

또 윈도우나 맥 환경에서는 권한 문제로 마운트가 실패하는 경우도 있어서, Docker Desktop 설정에서 파일 공유가 허용되어 있는지 꼭 봐야 해요.

Q. 특정 컨테이너를 재빌드할 때 추천하는 명령어가 있나요?

A. 저는 보통 docker-compose build [서비스명] 을 씁니다. 그리고 필요하면 docker-compose up -d --no-deps [서비스명] 으로 의존 서비스 없이 바로 실행해요.
예를 들어 API 서버만 재빌드하고 싶으면 이렇게 하면 되는데, 처음에는 전체를 다시 띄우느라 시간 낭비했었어요.

Q. Compose 파일 버전 3.9와 2의 차이점이 뭔가요?

A. 저도 예전엔 2 버전을 썼는데 3.9가 나온 뒤로는 최신 기능 지원이 더 잘 돼서 3 이상 버전을 쓰게 됐어요.
예를 들어 deploy 섹션이나 볼륨, 네트워크 정의 방식 등에서 차이가 있고, 3.9는 Swarm 모드와도 호환성이 더 좋아서 클라우드 배포할 때 유리해요.

Q. 로그를 한 번에 모니터링하는 좋은 방법 있나요?

A. 저는 docker-compose logs -f 명령어를 자주 씁니다. 이렇게 하면 모든 서비스 로그를 실시간으로 볼 수 있거든요.
특정 서비스 로그만 보고 싶으면 docker-compose logs -f 웹서비스명 이렇게 하면 돼요. 작업 중에 어디서 에러가 나는지 빠르게 찾아서 고치기 편하더라고요.

Q. Compose로 띄운 컨테이너 IP 확인하는 방법 알려 주세요.

A. 저는 보통 docker network inspect [네트워크명] 명령어를 사용해요. 네트워크 이름이 없으면 docker network ls로 찾아서, 관심 있는 네트워크를 살펴보면 관련 컨테이너 IP가 나옵니다.
예를 들어 기본 네트워크 이름은 보통 프로젝트명_default 이런 식이에요.

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

여기서 삽질했던 부분들

제가 가장 오래 고민했던 건 환경변수 중첩 문제였어요. 웹 컨테이너에는 DB 접속 정보를 넘겨야 하는데, docker-compose.override.yml로 덮어씌워서도 안 되고 .env 파일도 중복되서 꼬이고...

# .env 파일 예시
MYSQL_ROOT_PASSWORD=secretpassword
DB_HOST=db
DB_PORT=3306

이럴 땐 오히려 환경변수를 서비스별로 명확히 선언해주고, 덮어쓰기보다는 명확한 계층 구조로 쓰는 게 더 낫다는 걸 깨닫고 해결했습니다.

또 로컬 개발 중에 Windows에서 볼륨 권한 문제로 데이터베이스가 제대로 작동 안 했는데, Docker Desktop 설정에서 ‘File Sharing’에 작업 폴더를 추가하고 재시작하니까 바로 해결됐어요.

심화: 이렇게 해두면 더 좋더라고요

프로덕션과 개발 환경을 분리할 때 저는 여러 개 Compose 파일을 쓰는 방식을 추천해요.
예를 들어 기본 docker-compose.yml은 공통 설정, docker-compose.dev.yml은 개발 전용 설정, docker-compose.prod.yml는 배포 전용 설정 이런 식으로요.

실행할 때는 아래처럼 병합해요:

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

이렇게 하면 환경별 설정 충돌을 피하면서 깔끔하게 관리할 수 있더라고요.

그리고 저는 자주 쓰는 명령어는 쉘 스크립트로 만들어서 자동화해요. 예를 들어 테스트용 DB 초기화, 로그 모니터링 스크립트 이런 식으로요.

자주 물어보시는 것들 더 답해볼게요

Q. Compose 서비스에서 특정 커맨드로 진입하려면 어떻게 해야 하나요?

A. docker-compose exec [서비스명] bash 같은 형태로 진입할 수 있어요. 만약 bash가 없으면 sh로 바꿔서 시도해보시면 됩니다.

Q. Compose로 여러 컨테이너 중 일부만 삭제하고 싶을 때는?

A. docker-compose rm [서비스명] 명령어를 사용하면 됩니다. 중단 후 삭제할 때 유용해요.

Q. Compose 프로젝트 이름 변경은 어떻게 하나요?

A. 기본적으로 현재 폴더명이 프로젝트 이름으로 쓰이는데, docker-compose -p myproject up 이렇게 -p 옵션으로 지정할 수 있어요. 네트워크나 볼륨 이름에도 영향을 주니 참고하세요.

이렇게 정리하고 나니 Docker Compose 세팅하면서 흔히 겪는 문제가 훨씬 명확해졌어요. 실제로 저도 세팅할 때마다 이 글 내용을 하나씩 점검하면서 문제를 해결했거든요.

📌 함께 보면 좋은 글

• Linux 메모리 부족 문제, 저는 이렇게 원인 추적하고 해결했어요
• Nginx reverse proxy에 SSL 적용할 때 단계별로 막혔던 부분과 해결법
• SSH 키 관리 실수로 서버 잠겼던 경험과 복구하는 방법