도커 컴포즈 시작하기: 복잡한 컨테이너 관리를 한 번에 끝내는 방법
새로운 프로젝트를 시작할 때 웹 서버, 데이터베이스, 캐시 서버를 각각 따로 실행해 본 적이 있으신가요? docker run 명령어를 하나씩 입력하며 포트 번호를 외우고, 네트워크 설정을 맞추는 과정은 생각보다 고통스러워요. 실수로 명령어 하나만 빠뜨려도 서비스는 제대로 동작하지 않고, 팀원에게 환경을 공유할 때마다 “이 명령어 순서대로 입력하세요”라고 긴 매뉴얼을 전달해야 하죠.
이런 번거로운 과정을 겪고 있다면 지금 바로 도커 컴포즈 시작하기가 필요한 시점이에요. 여러 개의 컨테이너를 하나의 설정 파일로 묶어서 관리하면, 단 한 줄의 명령어로 전체 시스템을 통째로 올리고 내릴 수 있거든요. 마치 여러 악기가 모여 하나의 오케스트라 연주를 하듯, 컨테이너들을 지휘하는 마에스트로가 되는 셈이에요.
이 글을 끝까지 읽고 나면 복잡한 명령어 나열에서 벗어나, 깔끔한 설정 파일 하나로 인프라를 제어하는 즐거움을 느끼게 될 거예요. 주니어 개발자분들이 실무에서 바로 활용할 수 있도록 가장 핵심적인 내용만 담았어요.
- 도커 컴포즈가 왜 필요한지에 대한 근본적인 이유
- 실습을 위한 사전 준비물과 환경 체크리스트
- 실제 작동하는 docker-compose.yml 파일 작성법
- 컨테이너를 실행하고 상태를 확인하는 실전 명령어
- 자주 발생하는 설정 오류와 해결 노하우
실습 전 꼭 확인해야 할 사전 준비물과 핵심 개념
도커 컴포즈를 본격적으로 다루기 전에, 우리 컴퓨터에 무엇이 준비되어 있는지 확인해야 해요. 무턱대고 파일을 만들었다가는 환경 차이 때문에 오류 메시지만 마주하게 될 수 있거든요. 가장 먼저 확인해야 할 것은 도커 엔진(Docker Engine)이 정상적으로 설치되어 있는지 여부예요. 도커 컴포즈는 독립적인 프로그램이라기보다 도커를 기반으로 동작하는 도구이기 때문이에요.
또한, 설정 파일의 문법인 YAML(YAML Ain’t Markup Language) 형식을 이해하는 것이 중요해요. YAML은 사람이 읽기 매우 편한 구조를 가지고 있지만, 들여쓰기(Indentation) 하나만 틀려도 전체 파일이 망가지는 아주 예민한 규칙을 가지고 있어요. 탭(Tab) 대신 반드시 공백(Space)을 사용하는 습관을 들여야 해요.
도커만 사용할 때와 도커 컴포즈를 사용할 때 어떤 차이가 있는지 아래 표를 통해 비교해 보세요.
| 비교 항목 | Docker (단일 컨테이너) | Docker Compose (멀티 컨테이너) |
|---|---|---|
| 관리 단위 | 개별 컨테이너 하나하나 | 여러 컨테이너를 포함한 서비스 그룹 |
| 명령어 복잡도 | 매번 긴 명령어를 직접 입력 | 설정 파일에 적어두고 짧게 실행 |
| 네트워크 설정 | 직접 네트워크를 생성하고 연결 | 자동으로 서비스 간 네트워크 생성 |
| 환경 공유 | 명령어 스크립트를 전달해야 함 | YAML 파일 하나만 전달하면 끝 |
단순히 컨테이너 하나를 테스트할 때는 일반 도커 명령어가 빠를 수 있어요. 하지만 웹 서버와 DB가 결합된 환경, 혹은 팀원과 동일한 개발 환경을 맞춰야 하는 프로젝트라면 고민하지 말고 도커 컴포즈를 선택하는 것이 훨씬 효율적이에요.
실전! 도커 컴포즈를 이용한 웹 서비스 구축하기
이제 이론은 충분해요. 직접 손을 움직여서 웹 서버(Nginx)와 데이터 저장소(Redis)가 함께 돌아가는 환경을 만들어 볼게요. 이 과정은 약 30분 정도 소요되며, 차근차근 따라오시면 누구나 성공할 수 있어요.
STEP 1. 도커 컴포즈 설치 확인하기
가장 먼저 터미널을 열고 설치 여부를 확인해야 해요. 최근의 도커 데스크탑(Docker Desktop)을 설치했다면 이미 컴포즈가 포함되어 있을 확률이 높아요. 터미널에 다음 명령어를 입력해 보세요.
docker compose version
버전 정보가 출력된다면 준비 완료예요. 만약 명령어를 찾을 수 없다는 메시지가 나온다면, 도커를 최신 버전으로 업데이트하거나 공식 홈페이지에서 도커 컴포즈 플러그인을 별도로 설치해야 해요.
STEP 2. 실습용 디렉터리 생성 및 이동
파일들이 섞이지 않도록 전용 폴더를 만드는 것이 좋아요. 바탕화면이나 작업용 폴더에 다음과 같이 명령어를 입력해 주세요.
mkdir my-docker-app && cd my-docker-app
이제 이 폴더가 우리의 프로젝트 루트(Root) 디렉터리가 될 거예요. 모든 설정 파일은 이 폴더 안에 존재해야 도커 컴포즈가 인식할 수 있어요.
STEP 3. docker-compose.yml 파일 작성하기
가장 중요한 단계예요. 폴더 안에 docker-compose.yml이라는 이름의 파일을 만들고, 아래의 코드를 그대로 복사해서 붙여넣어 보세요. (메모장이나 VS Code 같은 에디터를 사용하세요!)
version: '3.8'
services:
web-server:
image: nginx:latest
ports:
- "8080:80"
networks:
- app-network
cache-server:
image: redis:alpine
networks:
- app-network
networks:
app-network:
driver: bridge방금 작성한 파일의 의미를 하나씩 뜯어볼까요? version은 컴포즈 파일의 규격 버전을 말해요. services 아래에는 우리가 실행할 컨테이너들이 나열되죠. web-server는 Nginx 이미지를 가져와서 내 컴퓨터의 8080 포트와 컨테이너의 80 포트를 연결(mapping)해요. cache-server는 가벼운 Redis 이미지를 사용하죠. 마지막으로 networks를 통해 두 컨테이너가 서로를 이름으로 찾을 수 있는 가상 네트워크를 만들었어요.
YAML 파일은 들여쓰기가 생명이에요! 위 코드에서
services: 아래의 web-server:는 반드시 공백 2칸 혹은 4칸으로 들여쓰기가 되어 있어야 해요. 만약 이 간격이 맞지 않으면 parsing error가 발생하며 실행되지 않아요.STEP 4. 컨테이너 실행하고 동작 확인하기
설정이 끝났다면 이제 마법을 부릴 시간이에요. 터미널에서 다음 명령어를 입력하세요.
docker compose up -d
여기서 -d 옵션은 ‘데몬(Daemon)’ 모드를 의미해요. 이 옵션을 붙여야 컨테이너가 백그라운드에서 조용히 돌아가고, 터미널을 계속 사용할 수 있어요. 명령어를 입력하면 도커가 자동으로 이미지를 내려받고(Pull), 네트워크를 만들고, 컨테이너를 실행할 거예요.
실행이 완료되었다면 브라우저를 열고 http://localhost:8080에 접속해 보세요. Nginx의 기본 환영 페이지가 보인다면 여러분은 방금 첫 번째 멀티 컨테이너 시스템을 성공적으로 구축한 거예요!
STEP 5. 상태 확인 및 로그 살펴보기
현재 실행 중인 컨테이너들이 잘 있는지 확인하려면 다음 명령어를 사용하세요.
docker compose ps
표 형태로 실행 중인 서비스 목록이 보일 거예요. 만약 서비스가 제대로 작동하지 않는 것 같다면, 로그를 통해 원인을 파악해야 해요. docker compose logs -f 명령어를 입력하면 실시간으로 어떤 일이 벌어지고 있는지 확인할 수 있어요.
실무에서는 컨테이너를 띄울 때 환경 변수(.env 파일)를 별도로 관리해요. 비밀번호나 API 키 같은 민감한 정보를 YAML 파일에 직접 적지 않고, 별도의 파일로 분리하여 도커 컴포즈가 읽어오도록 설정하는 것이 보안의 기본이에요.
자주 하는 실수와 해결법
도커 컴포즈를 처음 다루다 보면 누구나 실수를 해요. 가장 많이 마주치는 오류 유형들을 정리해 두었으니, 문제가 생기면 당황하지 말고 확인해 보세요.
❌ YAML 파일의 들여쓰기 오류
왜 발생하는가: 탭(Tab)과 공백(Space)을 혼용하거나, 들여쓰기 칸 수가 맞지 않을 때 발생해요.
✅ 해결법: 에디터(VS Code 등)에서 “Indent using spaces” 설정을 켜고, 모든 들여쓰기를 공백으로 통일하세요.
❌ 포트 충돌 (Port Conflict)
왜 발생하는가: 이미 내 컴퓨터의 8080 포트를 다른 프로그램(예: 다른 웹 서버)이 사용 중일 때 발생해요.
✅ 해결법: docker-compose.yml 파일의 ports 항목에서 왼쪽 숫자를 "9090:80"처럼 다른 번호로 바꿔보세요.
❌ 이미지 다운로드 실패
왜 발생하는가: 인터넷 연결이 불안정하거나, 입력한 이미지 이름에 오타가 있을 때 발생해요.
✅ 해결법: Docker Hub에서 이미지 이름을 정확히 확인하고, 네트워크 상태를 점검하세요.
❌ 컨테이너 간 통신 불가
왜 발생하는가: 서로 다른 네트워크에 속해 있거나, 서비스 이름을 잘못 호출했을 때 발생해요.
✅ 해결법: 같은 networks 섹션에 포함되어 있는지 확인하고, IP 주소 대신 서비스 이름(예: cache-server)을 사용하세요.
❌ 볼륨 권한 문제
왜 발생하는가: 호스트 컴퓨터의 폴더를 컨테이너와 연결(Volume Mount)할 때 읽기/쓰기 권한이 없을 때 발생해요.
✅ 해결법: 연결하려는 폴더의 권한을 확인하거나, 운영체제의 보안 설정을 체크하세요.
자주 묻는 질문
Q. 컨테이너를 완전히 끄고 삭제하려면 어떻게 하나요?
docker compose down 명령어를 사용하세요. 이 명령어를 실행하면 실행 중인 컨테이너뿐만 아니라 생성된 네트워크까지 깔끔하게 정리해 줘요.
Q. 설정 파일을 수정했는데 어떻게 적용하나요?
수정 후 다시 docker compose up -d를 입력하면 돼요. 도커 컴포즈가 변경된 부분만 감지해서 해당 컨테이너만 다시 생성하고 실행해 줍니다.
Q. docker-compose와 docker compose의 차이는 무엇인가요?
과거에는 하이픈(-)이 들어간 명령어를 썼지만, 최신 버전에서는 도커의 플러그인 형태인 docker compose(공백) 사용을 권장하고 있어요.
Q. 윈도우에서도 똑같이 쓸 수 있나요?
네, Docker Desktop for Windows를 설치하면 리눅스와 거의 동일한 환경에서 사용할 수 있어요.
Q. 컨테이너 로그를 실시간으로 보고 싶어요.docker compose logs -f 명령어를 입력하면 됩니다. 특정 서비스의 로그만 보고 싶다면 docker compose logs -f web-server처럼 이름을 붙여주세요.
마무리하며: 당신의 인프라 운영이 더 가벼워질 거예요
도커 컴포즈는 단순한 도구가 아니라, 개발자의 정신 건강을 지켜주는 든든한 조력자예요. 명령어를 일일이 외울 필요 없이, 잘 짜인 설정 파일 하나만 있으면 언제 어디서든 동일한 환경을 재현할 수 있으니까요. 오늘 배운 내용을 바탕으로 이제 복잡한 다중 컨테이너 환경도 두렵지 않을 거예요.
- 도커 컴포즈는 여러 컨테이너를 하나의 YAML 파일로 관리하는 도구예요.
- 설치 후
docker compose version으로 정상 작동을 확인하세요. - YAML 파일 작성 시 들여쓰기 규칙을 엄격히 지켜야 해요.
docker compose up -d로 백그라운드 실행을 시작하세요.- 문제가 생기면
docker compose logs로 원인을 파악하세요. - 정리가 필요할 땐
docker compose down을 사용하세요.
다음 단계로 나아가기 위해 오늘 바로 해보세요!
- 오늘 할 일: 실습용 디렉터리를 만들고 Nginx 컨테이너를 직접 띄워 보세요.
- 이번 주 할 일: DB(MySQL이나 PostgreSQL)를 추가하여 웹 서버와 연결해 보세요.
- 실행 직전 할 일: YAML 파일의 들여쓰기 규칙을 다시 한번 눈에 익혀 두세요.
지금 바로 터미널을 열고 첫 컨테이너를 띄워 보세요. 작은 성공이 쌓여 여러분의 실력을 만듭니다. 실습 중에 막히는 부분이 있다면 주저하지 말고 관련 커뮤니티를 찾아보거나 공식 문서를 참고해 보세요!
함께 읽으면 좋은 글: 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드
