컴포즈 파일 버전 지정, 왜 매번 에러가 날까요?
인터넷에서 찾은 예제 코드를 그대로 복사해서 붙여넣었는데, 갑자기 “version is obsolete” 혹은 “unsupported version” 같은 붉은색 에러 메시지가 화면을 채운 적이 있나요? 분명히 똑같은 도커를 쓰고 있는 것 같은데, 왜 내 컴퓨터에서만 실행이 안 되는지 답답한 마음이 들 거예요.
이런 문제는 대부분 도커 컴포즈(Docker Compose)의 버전 규격이 바뀌었거나, 현재 설치된 도커 엔진과 파일에 명시된 버전 정보가 서로 맞지 않아서 발생해요. 컨테이너 기술이 빠르게 발전하면서, 예전에 잘 작동하던 설정 파일이 지금은 더 이상 쓰이지 않는 구식이 되어버린 경우가 아주 많아요.
이제 막 컨테이너 운영의 세계에 발을 들인 주니어 개발자라면, 이 버전 문제 때문에 소중한 개발 시간을 허비하기 쉬워요. 하지만 원리만 정확히 이해하면 생각보다 아주 간단하게 해결할 수 있는 문제예요. 오늘 이 글을 통해 버전 충돌 없는 깨끗한 개발 환경을 만드는 법을 배워보세요.
이번 가이드에서는 다음과 같은 내용을 차근차근 다뤄볼게요.
- 도커 컴포즈 설치 상태와 버전을 확인하는 가장 정확한 방법
- 에러 없는 최소한의 컴포즈 설정 파일 작성 노하우
- 명령어 한 줄로 첫 번째 컨테이너 서비스를 띄우고 검증하기
- 실행 중 발생하는 흔한 실수와 즉각적인 해결책
본격적인 시작 전, 꼭 체크해야 할 준비물
무작정 파일을 만들기 전에 우리 컴퓨터에 무엇이 준비되어 있는지 확인하는 과정이 필요해요. 준비 없이 바로 명령어를 입력했다가는 환경 변수 문제나 권한 문제로 인해 삽질(?)을 하게 될 가능성이 높거든요.
도커 컴포즈 버전의 종류 이해하기
가장 먼저 알아야 할 점은 우리가 사용하는 도커 컴포즈가 크게 두 가지 형태로 존재한다는 사실이에요. 예전에는 Docker Compose V1이라는 이름으로 파이썬 기반의 도구가 쓰였지만, 지금은 Docker Compose V2라는 이름의 고(Go) 언어 기반 도구가 표준이 되었어요. V2는 도커 명령어와 통합되어 “docker compose”처럼 중간에 하이픈 없이 사용하는 것이 특징이에요.
이 차이를 모르면 명령어를 입력할 때마다 에러를 만날 수 있어요. 아래 표를 통해 현재 내가 어떤 환경을 지향해야 하는지 비교해 보세요.
| 구분 항목 | Docker Compose V1 | Docker Compose V2 (권장) |
|---|---|---|
| 명령어 형태 | docker-compose (하이픈 있음) | docker compose (공백 사용) |
| 주요 언어 | Python | Go |
| 속도 및 안정성 | 보통 | 매우 빠름 및 통합 관리 용이 |
| 버전 명시 규칙 | 파일 상단에 버전 필수 기재 | 버전 명시 생략 가능 (Compose Spec 적용) |
최근의 트렌드는 Docker Compose V2를 사용하는 것이에요. 최신 도커 데스크탑(Docker Desktop)을 설치했다면 이미 V2가 포함되어 있을 확률이 매우 높아요. 만약 리눅스 서버를 직접 운영한다면 별도로 패키지를 설치해야 할 수도 있으니 주의가 필요해요.
컴포즈 파일의 ‘version’ 필드는 예전에는 반드시 써야 했지만, 최신 규격인 Compose Specification에서는 생략해도 도커가 알아서 최신 방식으로 해석해 줘요. 하지만 협업을 위해 명시적으로 적어주는 습관도 나쁘지 않아요.
준비물이 모두 확인되었다면 이제 터미널을 열고 실제 실습을 시작할 준비를 마쳐보세요. 다음 단계에서 내 컴퓨터의 상태를 직접 확인해 볼게요.
컴포즈 파일 버전 시작하기 5단계 실습
이제 이론은 그만두고 직접 손을 움직여 볼 시간이에요. 아주 간단한 웹 서버와 데이터베이스를 띄워보는 과정을 통해 컴포즈의 동작 원리를 완벽하게 이해해 볼게요.
STEP 1. 설치 상태와 명령어 버전 확인하기
가장 먼저 해야 할 일은 내 시스템에 도커와 컴포즈가 제대로 설치되어 있는지 확인하는 일이에요. 터미널(또는 CMD, PowerShell)을 열고 아래 명령어를 입력해 보세요.
docker compose version
명령어를 입력했을 때 docker compose version v2.x.x와 같은 결과가 나온다면 준비 완료예요. 만약 command not found라는 메시지가 뜬다면, 도커가 설치되지 않았거나 환경 변수 설정이 누락된 상태이니 도커 엔진부터 설치해야 해요. 여기서 주의할 점은 반드시 띄어쓰기를 확인해야 한다는 점이에요. 하이픈을 넣은 docker-compose가 아니라 공백을 넣은 docker compose를 입력하는 것이 최신 표준이에요.
STEP 2. 실습용 디렉터리 생성과 이동
컴포즈 파일은 프로젝트 단위로 관리하는 것이 원칙이에요. 아무 곳에나 파일을 만들면 나중에 관리하기가 너무 힘들어져요. 전용 폴더를 만들어 볼까요?
- 먼저 프로젝트를 담을 폴더를 만들어요:
mkdir my-web-app - 생성한 폴더 안으로 들어가요:
cd my-web-app
이렇게 폴더를 따로 만드는 이유는 컴포즈가 실행될 때 해당 폴더 안에 있는 docker-compose.yml 파일을 기준으로 컨테이너들의 네트워크와 볼륨을 구성하기 때문이에요. 폴더가 곧 하나의 독립된 서비스 단위가 되는 셈이죠.
STEP 3. 최소 설정 파일(YAML) 작성하기
이제 핵심인 설정 파일을 만들 차례예요. 텍스트 에디터(VS Code 등)를 열고 폴더 안에 docker-compose.yml이라는 이름으로 새 파일을 만드세요. 아래 코드를 그대로 입력해 보세요. 우리는 웹 서버인 Nginx와 간단한 메모리 저장소인 Redis를 띄워볼 거예요.
version: '3.8'
services:
web-server:
image: nginx:latest
ports:
- "8080:80"
networks:
- app-network
cache-db:
image: redis:alpine
networks:
- app-network
networks:
app-network:
driver: bridge코드를 작성할 때 가장 중요한 것은 들여쓰기(Indentation)예요. YAML 파일은 탭(Tab)이 아니라 반드시 스페이스(Space)를 사용해야 해요. 위 예시에서 services: 아래의 web-server:는 2칸, 그 아래 image:는 다시 2칸이 들어가야 해요. 이 규칙을 어기면 바로 에러가 발생하니 꼭 주의하세요! 또한 ports: 항목에서 “8080:80”은 내 컴퓨터의 8080 포트를 컨테이너의 80 포트와 연결하겠다는 뜻이에요.
STEP 4. 컨테이너 실행하기
파일 작성이 끝났다면 이제 마법을 부릴 시간이에요. 터미널에서 아래 명령어를 입력해 보세요.
docker compose up -d
여기서 -d 옵션은 ‘Detached mode’의 약자예요. 이 옵션을 붙이지 않으면 터미널 창이 컨테이너의 로그로 가득 차버려서 명령어를 입력할 수 없게 돼요. 뒤에서 조용히 실행되도록 -d를 붙이는 습관을 들이는 게 좋아요. 명령어를 입력하면 도커가 이미지를 다운로드하고(Pulling), 컨테이너를 생성하고, 네트워크를 구성하는 과정을 실시간으로 보여줄 거예요.
STEP 5. 동작 확인 및 모니터링
모든 과정이 끝났다면 실제로 잘 돌아가고 있는지 확인해야겠죠? 두 가지 방법이 있어요.
첫째, 현재 실행 중인 컨테이너 목록을 확인하는 명령어를 써보세요: docker compose ps. 여기서 상태(Status)가 Up으로 표시된다면 성공이에요.
둘째, 웹 브라우저를 열고 주소창에 localhost:8080을 입력해 보세요. 만약 Nginx의 환영 페이지가 나타난다면 여러분은 방금 첫 번째 컨테이너 서비스를 성공적으로 띄운 거예요! 정말 멋지네요.
컨테이너 내부의 로그를 실시간으로 보고 싶다면
docker compose logs -f 명령어를 사용하세요. 서버 내부에서 어떤 일이 벌어지는지 생생하게 확인할 수 있어요.자주 하는 실수와 해결법 및 FAQ
실습 과정에서 누구나 한 번쯤은 마주칠 수 있는 문제들이 있어요. 당황하지 말고 아래의 해결책을 찾아보세요.
자주 하는 실수와 해결법
- ❌ YAML 파일 들여쓰기 오류
왜 발생하는가: 스페이스 대신 탭(Tab)을 사용했거나, 줄 맞춤이 어긋났을 때 발생해요.
✅ 해결법: 에디터 설정에서 ‘Tab을 Space로 변환’ 기능을 켜고, 반드시 일정한 간격(보통 2칸)을 유지하세요. - ❌ 포트 충돌 에러 (Address already in use)
왜 발생하는가: 이미 내 컴퓨터의 8080 포트를 다른 프로그램이 사용 중일 때 발생해요.
✅ 해결법:ports:설정에서 앞쪽 숫자를"8081:80"처럼 다른 숫자로 바꿔보세요. - ❌ 파일 경로 인식 불가
왜 발생하는가: 명령어를 입력하는 위치가docker-compose.yml파일이 있는 폴더가 아닐 때 발생해요.
✅ 해결법:ls(Windows는dir) 명령어로 파일이 있는지 확인하고,cd명령어로 올바른 폴더로 이동하세요. - ❌ 권한 거부 (Permission Denied)
왜 발생하는가: 리눅스 환경에서 도커 명령어를 실행할 권한이 없을 때 발생해요.
✅ 해결법: 명령어 앞에sudo를 붙여 실행하거나, 사용자를 docker 그룹에 추가하세요. - ❌ 이미지 다운로드 실패
왜 발생하는가: 인터넷 연결이 불안정하거나 이미지 이름에 오타가 있을 때 발생해요.
✅ 해결법: 이미지 이름이 정확한지 다시 확인하고, 인터넷 연결 상태를 체크하세요.
자주 묻는 질문
Q. 컴포즈 파일을 수정했는데 어떻게 적용하나요?
파일 내용을 수정한 뒤에는 다시 docker compose up -d를 입력하면 돼요. 도커가 변경 사항을 감지해서 수정된 부분의 컨테이너만 알아서 다시 만들고 교체해 준답니다.
Q. 실행 중인 컨테이너를 완전히 끄고 싶어요.
docker compose down 명령어를 사용하세요. 이 명령어는 컨테이너뿐만 아니라 생성된 네트워크까지 깔끔하게 정리해 줘요.
Q. ‘version’ 필드를 꼭 써야 하나요?
최신 도커 컴포즈(V2)에서는 생략해도 동작해요. 하지만 프로젝트의 명확성을 위해 version: '3.8'과 같이 명시하는 것이 협업 시 혼선을 줄이는 좋은 습관이에요.
Q. 컨테이너 내부로 직접 들어가서 명령어를 치고 싶어요.
docker compose exec web-server sh(또는 bash) 명령어를 입력하면 실행 중인 컨테이너 안으로 접속할 수 있어요.
성공적인 컨테이너 운영을 위한 마무리
오늘 우리는 컴포즈 파일의 버전을 확인하는 법부터 실제 서비스를 띄우는 과정까지 모두 경험해 보았어요. 처음에는 복잡해 보였겠지만, 규칙만 잘 지키면 컨테이너 운영은 정말 강력하고 편리한 도구가 될 거예요.
- 도커 컴포즈 V2는
docker compose(공백)로 사용하세요. - YAML 파일 작성 시 들여쓰기는 생명입니다. (탭 대신 스페이스 사용)
- 포트 충돌이 나면 왼쪽 포트 번호를 변경하세요.
- 서비스를 띄울 때는
-d옵션으로 백그라운드 실행을 생활화하세요. - 정리는
docker compose down으로 깔끔하게!
오늘 배운 내용을 바탕으로 지금 바로 자신만의 실습 디렉터리를 만들고 첫 컨테이너를 띄워 보세요. 작은 성공이 쌓여 단단한 개발 역량이 될 거예요.
다음 단계로 나아가기:
컨테이너를 띄우는 데 성공했다면, 이제는 데이터를 영구적으로 저장하는 방법인 볼륨(Volumes) 설정과 컨테이너 간의 복잡한 통신을 관리하는 네트워크(Networks)를 깊이 있게 파헤쳐 볼 차례예요.
관련하여 더 깊은 내용이 궁금하시다면 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 참고해 보세요.
