도커 컴포즈 설치 시작하기: 왜 지금 필요한가요?
터미널 창을 열고 수많은 명령어를 입력하다가 문득 이런 생각이 든 적이 있지 않나요? “이 복잡한 설정을 매번 타이핑해야 한다니, 정말 너무 비효율적이야!”
데이터베이스를 띄우고, 웹 서버를 연결하고, 캐시 서버를 추가하는 과정에서 하나라도 명령어를 빼먹으면 서비스는 제대로 돌아가지 않아요. 컨테이너 하나를 실행할 때마다 길어지는 명령어를 외우는 것은 주니어 개발자에게 너무나 가혹한 일입니다.
이런 번거로움을 한 번에 해결해 주는 도구가 바로 도커 컴포즈(Docker Compose)예요. 여러 개의 컨테이너를 하나의 설정 파일로 묶어서 관리할 수 있게 도와주기 때문에, 마치 마법 주문 하나로 복잡한 시스템 전체를 가동하는 것과 같은 경험을 할 수 있어요.
요즘 데브옵스(DevOps) 환경에서는 단일 컨테이너보다 여러 서비스가 유기적으로 연결된 마이크로서비스 아키텍처가 대세예요. 따라서 도커 컴포즈를 다루는 능력은 이제 선택이 아닌 필수 역량이 되었답니다. 오늘 이 글을 끝까지 읽으시면 설치부터 실제 서비스 가동까지 막힘없이 해내실 수 있어요.
도커 컴포즈는 여러 컨테이너를 정의하고 실행하기 위한 도구로, YAML 형식의 파일을 사용하여 설정 내용을 저장합니다.
이 글에서 함께할 내용
- 도커 컴포즈 설치를 위한 사전 환경 점검
- 운영체제별 도커 컴포즈 설치 및 버전 확인 방법
- 실제 서비스 운영을 위한 최소 설정 파일 작성법
- 컨테이너 실행, 모니터링, 정리하는 전체 프로세스
사전 준비: 설치 전 반드시 확인해야 할 체크리스트
도커 컴포즈를 설치하기 전에 먼저 확인해야 할 중요한 전제 조건이 있어요. 도커 컴포즈는 단독으로 작동하는 프로그램이 아니라, 도커 엔진(Docker Engine) 위에서 실행되는 보조 도구이기 때문이에요.
만약 컴퓨터에 도커 자체가 깔려 있지 않다면, 아무리 컴포즈 설치 명령어를 입력해도 오류 메시지만 보게 될 거예요. 따라서 반드시 도커가 정상적으로 구동 중인지 먼저 확인하는 습관을 가져야 합니다.
실행 환경 선택 가이드
개발 환경에 따라 설치 방식이 완전히 달라져요. 본인이 어떤 환경에서 작업할지 먼저 결정해야 합니다.
| 운영체제 | 권장 설치 방식 | 주요 특징 |
|---|---|---|
| Ubuntu/Linux | 바이너리 직접 다운로드 | 서버 환경에서 가장 많이 사용하며 제어가 자유로워요. |
| macOS | Docker Desktop 설치 | 설치 시 컴포즈가 자동으로 포함되어 매우 간편해요. |
| Windows | Docker Desktop 설치 | WSL2 기반으로 연동되어 데스크톱 환경에 최적화되어 있어요. |
꼭 알아야 할 핵심 용어
도커 컴포즈를 다루다 보면 생소한 단어들이 자주 등장해요. 개념을 미리 잡아두면 훨씬 수월합니다.
- 서비스(Service): 컨테이너의 역할을 정의하는 단위예요. 예를 들어 ‘web’ 서비스, ‘db’ 서비스라고 부를 수 있어요.
- 이미지(Image): 컨테이너를 만들기 위한 설계도와 같아요. Nginx나 MySQL 같은 이미지를 불러와 사용합니다.
- 볼륨(Volume): 컨테이너가 삭제되어도 데이터가 사라지지 않도록 보존하는 저장 공간이에요.
- 네트워크(Network): 여러 컨테이너가 서로 통신할 수 있도록 연결해 주는 통로 역할을 해요.
Linux 서버 환경에서 설치할 때는 반드시 sudo 권한이 필요해요. 권한 설정이 제대로 되지 않으면 명령어가 실행되지 않을 수 있으니 주의하세요.
도커 컴포즈 설치 및 첫 실행 실습
이제 본격적으로 도커 컴포즈를 설치하고, 실제로 서비스를 띄워볼 차례예요. 단계별로 차근차근 따라오시면 됩니다.
STEP 1. 운영체제별 도커 컴포즈 설치하기
먼저 본인의 환경에 맞는 설치 방법을 선택해 주세요. 가장 많이 쓰이는 Linux와 간편한 Desktop 버전으로 나누어 설명할게요.
Linux(Ubuntu 등) 환경에서는 터미널에서 명령어를 통해 최신 버전을 내려받아야 해요. 아래 명령어를 순서대로 입력하세요.
- 먼저 GitHub에서 최신 릴리스 파일을 다운로드합니다:
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose - 파일에 실행 권한을 부여합니다:
sudo chmod +x /usr/local/bin/docker-compose
macOS 및 Windows 환경은 훨씬 간단해요. 이미 Docker Desktop을 설치했다면, 도커 컴포즈는 이미 설치되어 있을 확률이 매우 높습니다. 별도의 과정을 거칠 필요 없이 바로 다음 단계로 넘어가시면 돼요.
STEP 2. 설치 확인 및 버전 체크
설치가 제대로 끝났는지 확인하는 과정은 매우 중요해요. 터미널이나 명령 프롬프트(CMD)를 열고 아래 명령어를 입력해 보세요.
docker compose version
명령어를 입력했을 때 “Docker Compose version v2.x.x”와 같이 버전 정보가 나타난다면 성공적으로 설치된 것이에요. 만약 “command not found”라는 메시지가 뜬다면 설치 경로가 꼬였거나 설치 과정에서 오류가 발생한 것이니 다시 한번 확인해 보세요.
STEP 3. 최소 설정 파일(docker-compose.yml) 작성하기
설치가 끝났으니 이제 마법의 주문인 설정 파일을 만들어야 해요. 실습을 위해 아주 간단한 웹 서버를 띄워볼게요. 적당한 폴더를 하나 만들고, 그 안에 docker-compose.yml이라는 이름의 파일을 생성하세요.
파일 안에는 아래 내용을 그대로 복사해서 붙여넣어 보세요. (들여쓰기가 매우 중요하니 주의하세요!)
version: '3.8'
services:
web-server:
image: nginx:latest
ports:
- "8080:80"
위 설정의 의미를 하나씩 짚어볼까요?
- version: ‘3.8’: 도커 컴포즈 파일 규격의 버전을 지정해요.
- services: 우리가 실행할 컨테이너들의 묶음이에요.
- web-server: 우리가 임의로 붙인 서비스의 이름이에요.
- image: nginx:latest: Nginx라는 웹 서버 이미지를 사용하겠다는 뜻이에요.
- ports: “8080:80”: 내 컴퓨터의 8080번 포트로 접속하면 컨테이너 내부의 80번 포트로 연결해 주라는 설정이에요.
STEP 4. 컨테이너 실행과 동작 확인
이제 준비는 모두 끝났어요. 터미널에서 해당 파일이 있는 폴더로 이동한 뒤, 아래 명령어를 입력하여 서비스를 시작하세요.
docker compose up -d
여기서 -d 옵션은 detached mode를 의미해요. 이 옵션을 붙여야 컨테이너가 백그라운드에서 조용히 돌아가며, 터미널을 계속 사용할 수 있어요. 만약 이 옵션을 빼면 터미널 창에 실시간 로그가 계속 찍히면서 다른 명령어를 입력할 수 없게 됩니다.
실행이 완료되었다면, 웹 브라우저를 열고 http://localhost:8080 주소로 접속해 보세요. “Welcome to nginx!”라는 문구가 보인다면 여러분은 방금 첫 번째 도커 컴포즈 서비스를 성공적으로 가동시킨 거예요!
STEP 5. 상태 모니터링 및 정리하기
서비스가 잘 돌아가고 있는지 확인하고 싶을 때는 docker compose ps 명령어를 사용하세요. 현재 실행 중인 서비스 목록과 상태를 한눈에 볼 수 있어요.
만약 실습을 마치고 컨테이너를 완전히 종료하고 싶다면, 아래 명령어를 입력하면 됩니다.
docker compose down
이 명령어를 사용하면 실행 중인 컨테이너를 멈추고, 생성되었던 네트워크까지 깔끔하게 삭제해 줍니다. 마치 작업을 마치고 책상을 정리하는 것과 같죠.
만약 서비스 로그만 보고 싶다면
docker compose logs -f 명령어를 사용하세요. 실시간으로 컨테이너 내부에서 어떤 일이 일어나는지 관찰할 수 있습니다.자주 하는 실수와 해결법
도커 컴포즈를 처음 사용하다 보면 예상치 못한 오류 때문에 당황할 때가 많아요. 가장 빈번하게 발생하는 문제 5가지를 정리했습니다.
- ❌ YAML 파일의 들여쓰기 오류
왜 발생하나요? YAML은 공백(Space)의 개수로 계층 구조를 구분하는데, 탭(Tab)을 섞어 쓰거나 공백 개수가 맞지 않으면 문법 오류가 나요.
✅ 해결법: 반드시 스페이스바를 사용하고, VS Code 같은 에디터에서 YAML 확장 프로그램을 설치해 눈으로 직접 구조를 확인하세요. - ❌ 포트 충돌 오류 (Bind for 0.0.0.0:8080 failed)
왜 발생하나요? 이미 내 컴퓨터의 8080번 포트를 다른 프로그램이 사용하고 있기 때문이에요.
✅ 해결법:ports설정에서 앞의 숫자(호스트 포트)를 8081이나 9000처럼 다른 번호로 바꿔주세요. - ❌ 권한 거부 (Permission Denied)
왜 발생하나요? Linux 환경에서 도커 명령어에 접근할 권한이 없기 때문이에요.
✅ 해결법: 명령어 앞에sudo를 붙이거나, 현재 사용자를 docker 그룹에 추가하세요. - ❌ 이미지 다운로드 실패 (Manifest not found)
왜 발생하나요? 오타가 있거나 존재하지 않는 이미지를 호출했기 때문이에요.
✅ 해결법: Docker Hub에서 이미지 이름과 태그(latest 등)가 정확한지 다시 한번 확인하세요. - ❌ 데이터가 사라지는 현상
왜 발생하나요? 컨테이너 내부에만 데이터를 저장하면 컨테이너 삭제 시 데이터도 함께 사라져요.
✅ 해결법: Volumes 설정을 통해 호스트 컴퓨터의 폴더와 컨테이너 내부 폴더를 연결해 주세요.
자주 묻는 질문
Q. docker-compose와 docker compose는 무엇이 다른가요?
예전에는 하이픈(-)이 들어간 별도의 프로그램을 설치해야 했지만, 최신 버전에서는 도커 엔진의 플러그인 형태로 통합되었어요. 따라서 이제는 하이픈 없이 docker compose라고 쓰는 것이 표준입니다.
Q. 설정 파일을 수정하면 바로 반영되나요?
아니요, 파일을 수정했다면 docker compose up -d를 다시 입력해야 해요. 그러면 도커가 변경된 부분을 감지하고 해당 서비스만 새로 생성하여 적용해 줍니다.
Q. 컨테이너가 자꾸 꺼져요. 어떻게 하나요?
컨테이너 내부에서 실행 중인 프로세스가 종료되었을 가능성이 커요. docker compose logs 명령어를 통해 어떤 에러 메시지가 출력되었는지 반드시 확인해야 합니다.
Q. 윈도우에서도 Linux와 똑같이 쓸 수 있나요?
네, Docker Desktop을 설치하면 내부적으로 WSL2라는 기술을 통해 Linux와 거의 유사한 환경을 제공하므로 명령어 사용 방식은 동일합니다.
Q. 여러 개의 docker-compose.yml 파일을 동시에 쓸 수 있나요?
네, -f 옵션을 사용하면 원하는 파일을 지정하여 실행할 수 있습니다. 예: docker compose -f docker-compose.dev.yml up -d
핵심 요약과 다음 단계
오늘 우리는 도커 컴포즈 설치 시작하기부터 실제 서비스 가동까지의 모든 과정을 살펴보았어요. 처음에는 낯설 수 있지만, 한 번 익숙해지면 컨테이너 관리가 정말 편리해진다는 것을 느끼실 거예요.
- 도커 컴포즈는 여러 컨테이너를 YAML 파일 하나로 관리하는 도구예요.
- Linux는 바이너리 설치, Desktop 버전은 자동 설치를 권장해요.
- 설치 후에는 반드시
docker compose version으로 확인하세요. - YAML 파일 작성 시 들여쓰기(Space)를 철저히 지켜야 해요.
- 서비스 실행은
up -d, 종료는down을 사용하세요.
성장을 위한 다음 단계
도커 컴포즈에 익숙해졌다면 이제 다음 단계로 넘어가 볼 시간이에요.
- 오늘 할 일: 실습용 디렉터리를 만들고 위 예제 코드를 복사해 첫 Nginx 컨테이너를 띄워 보세요.
- 이번 주 할 일: DB(MySQL이나 PostgreSQL) 서비스를 추가하여 웹 서버와 연결하는 작업을 시도해 보세요.
- 실행 직전 할 할 일: Docker Volume의 개념을 공부하여 데이터 보존 방법을 익혀 두세요.
지금 바로 터미널을 열고 첫 컨테이너를 띄워 보세요. 직접 명령어를 입력하고 브라우저에서 결과물을 확인하는 순간, 여러분의 개발 실력은 한 단계 더 성장할 거예요!
도커의 더 깊은 내용이 궁금하다면 아래 글을 참고해 보세요.
도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드
