개발 환경을 구성할 때 가장 번거로운 부분은 서비스마다 다른 의존성 설치와 실행 순서입니다.
예를 들어 웹 애플리케이션 하나를 실행하기 위해 Node.js, DB, 캐시, 메시징 큐 등을 각각 따로 설치해야 하고, 각 서비스의 버전도 팀원마다 달라 충돌이 생기기 쉽습니다.
이 문제를 단순하게 해결하는 방법이 바로 Docker Compose입니다.
Docker Compose는 여러 컨테이너를 하나의 프로젝트처럼 묶어 손쉽게 실행하고 정리할 수 있도록 도와주는 도구입니다.
로컬 개발환경을 만들 때 사실상 표준으로 자리 잡은 이유가 여기에 있습니다.
1. Docker Compose란 무엇인가
Docker Compose는 여러 Docker 컨테이너를 하나의 YAML 설정 파일(docker-compose.yml) 로 정의하고,
docker compose up 한 번으로 전체 개발환경을 시작하도록 만드는 오케스트레이션 도구입니다.
단일 컨테이너 실행이 Docker 엔진의 영역이라면,
여러 개의 컨테이너를 묶어 서비스처럼 관리하는 역할이 Compose의 본질입니다.
예를 들어 웹 서버, 데이터베이스, 캐시 서버를 각각 컨테이너로 나누어 실행할 때
Compose 파일 하나에 다음을 정의할 수 있습니다.
- 어떤 이미지를 사용할지
- 어떤 포트를 열지
- 어떤 환경 변수를 쓸지
- 어떤 컨테이너끼리 네트워크를 공유할지
- 데이터는 어디에 저장할지(볼륨)
- 실행 순서는 어떻게 할지
이렇게 작성한 설정 파일을 모든 팀원이 공유하면
누가 실행해도 동일한 개발환경을 100% 재현할 수 있습니다.
2. 왜 로컬 개발환경에 Docker Compose가 필요한가
Docker Compose가 중요한 이유는 “환경 차이”로 인한 문제를 원천적으로 제거하기 때문입니다.
기존 방식에서는 로컬 OS, 설치된 도구 버전, 시스템 설정 등 다양한 요인이 애플리케이션 동작에 영향을 줬습니다.
하지만 Compose를 사용하면 다음과 같은 장점이 생깁니다.
첫째, 개발환경 재현성이 높습니다.
YAML 파일만 복사하면 누구나 동일한 환경에서 개발을 시작할 수 있습니다.
둘째, 의존성이 많은 프로젝트에서 특히 강력합니다.
DB나 캐시, 큐 같은 부가 서비스를 직접 설치할 필요 없이 컨테이너로 함께 띄우면 됩니다.
셋째, 실행/중지/정리가 쉬워집니다.
커맨드 한 줄로 전체 개발환경을 올리고 내릴 수 있기 때문에
“환경 세팅에 하루 종일 걸리는 문제”를 없애줍니다.
마지막으로, 실제 서비스와 유사한 환경을 로컬에서 그대로 재현할 수 있습니다.
운영 환경을 컨테이너 기반으로 구성한다면, 로컬 환경도 같은 방식으로 구성해
개발-테스트-운영의 차이를 줄일 수 있습니다.
3. Docker Compose 기본 예제 이해하기
Node.js 애플리케이션과 MySQL 데이터베이스를 함께 사용하는 프로젝트를 로컬에서 구성한다고 가정해보겠습니다. Docker Compose를 사용하면 두 서비스를 하나의 설정으로 묶어 손쉽게 실행할 수 있습니다.
우선 애플리케이션을 담당하는 app 서비스는 현재 프로젝트 폴더에 있는 Dockerfile을 기반으로 이미지를 빌드하도록 구성되어 있습니다. 개발자가 웹 브라우저에서 접근할 수 있도록 로컬 머신의 3000번 포트를 컨테이너 내부의 동일한 포트로 연결합니다. 또한 이 애플리케이션이 데이터베이스에 접근하기 위해서는 MySQL 컨테이너가 먼저 실행되어야 하므로, app 서비스는 db 서비스에 의존한다는 설정도 포함되어 있습니다. 내부적으로 데이터베이스 연결을 위해 호스트 이름, 사용자명, 비밀번호 같은 기본 환경 변수도 함께 지정되어 있습니다. 개발 중에 코드가 자주 변경되므로, 프로젝트 폴더 전체를 컨테이너 내부의 /app 디렉터리에 볼륨으로 연결하여 소스 코드가 변경될 때마다 컨테이너에 즉시 반영되도록 구성되어 있습니다.
다음으로 데이터베이스 역할을 하는 db 서비스는 MySQL 8 공식 이미지를 기반으로 실행됩니다. 초기 설정은 단순하게 루트 비밀번호만 지정하면 되며, 로컬 환경에서도 MySQL 클라이언트로 직접 접속할 수 있도록 3306 포트를 외부로 노출합니다. 데이터베이스 데이터는 컨테이너가 종료되거나 재시작되더라도 유지되어야 하기 때문에, MySQL의 데이터 디렉터리는 db_data라는 Docker 볼륨에 연결됩니다. 이 볼륨은 컨테이너 생명주기와 관계없이 독립적으로 남아 있어, 개발 환경을 여러 번 재실행해도 데이터가 그대로 보존됩니다.
마지막으로 Compose 설정에는 db_data라는 이름의 볼륨이 정의되어 있어, MySQL 컨테이너가 생성되는 순간 자동으로 이 볼륨을 사용하게 됩니다. 두 컨테이너는 Docker Compose가 자동으로 생성하는 동일한 네트워크 환경을 공유하므로, app 서비스는 특별한 주소 설정 없이 단순히 db라는 이름으로 MySQL 컨테이너에 접근할 수 있습니다.
이 구성은 Node.js 애플리케이션과 MySQL 데이터베이스를 하나의 개발환경처럼 묶어주며, 개발자는 docker compose up 한 번만 실행하면 두 컨테이너가 동시에 준비되고 서로 연결된 상태로 실행됩니다. 반대로 작업을 마친 뒤에는 docker compose down 명령으로 모든 컨테이너와 네트워크를 정리할 수 있어 개발환경 초기화도 매우 간단합니다.
4. Docker Compose로 로컬 개발환경 구축하는 전체 흐름
Docker Compose 기반 개발환경 구축 과정은 다음과 같은 단계로 이루어집니다.
첫 번째 단계는 프로젝트 폴더에 docker-compose.yml 파일을 만들고, 서비스 목록을 선언하는 것입니다.
각 서비스는 어떤 Docker 이미지 또는 Dockerfile을 사용할지, 포트와 환경 변수는 무엇인지, 볼륨은 어디에 연결할지 등 구체적인 설정을 포함합니다.
두 번째 단계는 관련 데이터베이스나 캐시 같은 외부 자원을 컨테이너로 선언하는 것입니다.
MySQL, PostgreSQL, Redis, MongoDB 등 대부분의 서비스는 이미 공식 Docker 이미지를 제공하므로 설정이 매우 간단합니다.
세 번째 단계는 네트워크 설정입니다.
Compose는 기본적으로 모든 컨테이너를 동일한 네트워크에 배치하므로
컨테이너 이름만으로 서로 접근할 수 있습니다.
예를 들어 db 컨테이너의 주소는 db:3306처럼 간단하게 접근 가능합니다.
네 번째 단계는 docker compose up --build로 환경을 실행하는 것입니다.
컨테이너들이 정상적으로 올라가면 로컬 개발환경이 완성됩니다.
종료할 때는 docker compose down 한 번이면 컨테이너와 네트워크를 깔끔하게 정리할 수 있습니다.
5. 개발환경 최적화를 위한 Compose 활용 팁
Compose를 효율적으로 활용하려면 몇 가지 베스트 프랙티스를 적용하는 것이 좋습니다.
우선, 소스 코드와 연결된 볼륨을 적극 활용하면 코드 수정 시 컨테이너를 재시작하지 않아도 변경 사항이 즉시 반영됩니다. 특히 Node.js, Django, Laravel 같은 서버 프레임워크는 파일 변경을 감지해 자동으로 재시작하는 기능이 있어 훨씬 편리합니다.
또한 .env 파일을 Compose에 연결해 환경 변수를 관리하면 브랜치별, 팀원별 환경 구성이 단순해집니다. 같은 설정을 여러 사람이 공유할 때 매우 유용합니다.
마지막으로, 실제 운영환경이 Docker 기반이라면 로컬 Compose 환경에서도 운영환경과 최대한 비슷한 구조를 유지하는 것이 좋습니다. 이렇게 하면 개발에서 발견한 문제가 운영에서 그대로 재현되는 장점이 있습니다.
6. 결론
Docker Compose는 여러 컨테이너로 구성된 개발환경을 하나의 설정 파일로 관리하고,
한 번에 실행·중지할 수 있는 강력한 도구입니다.
개발자들이 개별적으로 설치하던 다양한 서비스를 컨테이너로 대체할 수 있어
팀 전체의 작업 속도를 높이고 환경 차이에 따른 문제를 거의 없앨 수 있습니다.
단순한 웹 프로젝트부터 복잡한 마이크로서비스 구조까지 모두 지원하며,
로컬 개발환경·테스트 환경·운영 환경 간의 일관성을 유지하는 데에도 큰 도움이 됩니다.
로컬 개발환경 구축이 복잡하거나, 팀원 간 환경 차이로 문제를 겪고 있다면
Docker Compose는 가장 빠르고 안정적인 해결책이 됩니다.