[IT-정보] 컴포즈 파일 버전 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드

도커 컴포즈 버전 설정 때문에 막막했던 경험이 있나요?

팀 동료가 준 docker-compose.yml 파일을 내 로컬 서버에 그대로 복사해서 실행했는데, 갑자기 빨간색 에러 메시지가 터져 나온 적이 있나요? 분명히 같은 도커를 쓰고 있고 똑같은 명령어를 입력했는데, 버전 정보가 맞지 않는다며 실행조차 거부당하면 정말 당황스러워요. 서버 운영자라면 이런 상황이 단순한 오타 때문인지, 아니면 내가 모르는 엔진의 버전 차이 때문인지 판단하는 것부터가 커다란 숙제처럼 느껴지곤 해요.

많은 백엔드 개발자들이 컨테이너 환경을 구축할 때 가장 먼저 마주하는 벽이 바로 이 컴포즈 파일 버전이에요. 단순히 숫자 몇 개를 적는 것이라고 생각하기 쉽지만, 사실 이 숫자는 도커 엔진이 이 파일을 어떻게 해석하고 어떤 기능을 지원할지를 결정하는 아주 중요한 약속이에요. 버전을 잘못 지정하면 네트워크 설정이 꼬이거나, 볼륨 마운트가 제대로 되지 않아 소중한 데이터가 날아갈 수도 있어요.

특히 최근에는 도커 컴포즈의 패러다임이 완전히 바뀌면서, 예전 방식대로 버전을 명시해야 하는지 아니면 아예 생략해도 되는지에 대한 혼란이 더 커졌어요. 구글링을 해도 버전 2와 버전 3의 차이점에 대한 글은 많지만, 정작 지금 내가 쓰는 환경에서 무엇을 써야 가장 안정적인지에 대한 답을 찾기는 쉽지 않죠. 이런 혼란을 끝내기 위해 이번 글을 준비했어요.

이 글을 끝까지 읽고 나면 여러분은 다음과 같은 능력을 갖추게 될 거예요.

컴포즈 파일 상단에 적는 버전 숫자의 진짜 의미를 이해해요.
버전 2와 버전 3, 그리고 최신 규격의 결정적인 차이점을 구분해요.
내 환경에 맞는 최적의 설정법을 선택해 에러 없는 컨테이너 환경을 구축해요.
실무에서 흔히 발생하는 버전 관련 트러블슈팅 능력을 키워요.

본격적인 시작 전, 꼭 알아야 할 핵심 개념 정리

컴포즈 파일을 작성하기 전에 우리가 사용하는 도구들이 어떤 규칙을 따르고 있는지 명확히 아는 것이 우선이에요. 단순히 명령어를 외우는 것보다, 컴포즈 파일 버전 정리의 기초가 되는 용어들을 이해하면 나중에 환경이 바뀌어도 당황하지 않아요.

컴포즈 버전과 스펙의 차이

우리가 흔히 말하는 ‘버전’은 두 가지 의미를 담고 있어요. 첫 번째는 파일 상단에 명시하는 `version: ‘3.8’`과 같은 파일 스펙 버전이에요. 이는 이 파일이 어떤 문법과 기능을 담고 있는지를 정의해요. 두 번째는 우리가 터미널에서 실행하는 도커 컴포즈 도구 자체의 버전이에요. 파일 스펙이 아무리 최신이라도, 도커 컴포즈 도구가 너무 옛날 버전이면 파일을 읽지 못하고 오류를 뱉어내요. 이 두 가지가 서로 짝이 맞아야 한다는 점을 꼭 기억해야 해요.

버전 선택을 위한 판단 기준 비교

무조건 최신 버전을 쓴다고 좋은 것은 아니에요. 현재 운영 중인 서버의 도커 엔진 버전과 내가 사용할 기능(예: Docker Swarm 사용 여부)에 따라 선택 기준이 달라져요. 아래 표를 통해 상황별로 어떤 버전을 고려해야 하는지 확인해 보세요.

구분 항목	버전 2.x 계열	버전 3.x 계열	최신 Compose Spec
주요 목적	단일 호스트 운영	Docker Swarm 클러스터	모든 환경 통합
네트워크 제어	매우 세밀한 설정 가능	Swarm에 최적화된 간소화	기존 제약 해소
권장 환경	구형 레거시 서버	오케스트레이션 필요 시	최신 Docker 환경

💡 알아두기
버전 2와 3의 가장 큰 차이는 컨테이너 배포 방식에 있어요. 단일 서버에서만 돌릴 계획이라면 버전 2의 기능들이 더 유용할 때가 있지만, 현대적인 클라우드 환경으로 확장할 계획이라면 버전 3 기반의 설계를 고려해야 해요.

결국 좋은 버전 선택이란, 현재 내 서버의 사양과 앞으로의 확장 계획 사이에서 균형을 잡는 과정이에요. 무작정 최신 기능을 쫓기보다는, 내가 사용 중인 도커 엔진(Docker Engine)이 지원하는 스펙 범위를 먼저 확인하는 습관을 들여야 해요.

컴포즈 파일 버전 지정의 핵심 단계별 실행 가이드

이제 실전으로 들어가서 컴포즈 파일을 어떻게 구성하고 버전을 어떻게 다루어야 하는지 단계별로 살펴볼게요. 단순히 숫자를 적는 것을 넘어, 각 단계가 전체 컨테이너 운영에 어떤 영향을 주는지 이해하는 것이 중요해요.

STEP 1. 파일 상단의 버전 선언 이해하기

모든 docker-compose.yml 파일의 첫 줄은 대개 `version: ‘3.8’`과 같은 형태로 시작해요. 여기서 숫자는 단순한 순서가 아니라, 도커 컴포즈 엔진에게 “이 파일은 이런 문법으로 작성되었으니, 이 규칙에 맞춰서 해석해 줘”라고 요청하는 일종의 프로토콜이에요. 만약 버전 3.8을 선언했는데, 당신의 도커 엔진이 3.5까지만 지원한다면 실행 즉시 구문 에러(Syntax Error)가 발생하게 돼요.

과거에는 이 버전 선언이 필수적이었지만, 최신 도커 컴포즈(V2)에서는 이 필드가 점차 사라지는 추세예요. 최신 엔진은 파일의 내용을 보고 자동으로 가장 적절한 스펙을 적용하는 Compose Specification 방식을 따르기 때문이죠. 하지만 호환성을 위해 명시하는 습관은 여전히 유효해요.

STEP 2. 버전 2와 버전 3의 기술적 차이 분석

가장 많은 질문이 나오는 부분이죠. 버전 2와 3은 설계 철학 자체가 달라요. 버전 2는 단일 서버 내에서 컨테이너 간의 복잡한 네트워크 통신이나 볼륨 공유를 아주 세밀하게 제어하는 데 초점이 맞춰져 있어요. 반면 버전 3는 여러 대의 서버를 하나로 묶어 관리하는 Docker Swarm 환경을 염두에 두고 만들어졌어요.

예를 들어, 네트워크 설정에서 특정 컨테이너가 어떤 브리지 네트워크에 속할지, IP를 어떻게 할당받을지를 정교하게 짤 수 있는 건 버전 2의 장점이에요. 하지만 Swarm 모드에서 컨테이너를 여러 노드에 분산 배치하고 싶다면 반드시 버전 3의 `deploy` 옵션을 사용해야 해요. 버전 2에는 `deploy`라는 개념이 없거든요. 따라서 서비스가 커질 가능성이 있다면 처음부터 버전 3로 설계를 시작하는 것이 유리해요.

STEP 3. 최신 Compose Specification 환경 구축하기

최근의 트렌드는 특정 버전에 얽매이지 않는 Compose Spec을 사용하는 것이에요. 도커는 이제 버전 2.x, 3.x를 나누는 대신, 하나의 통합된 규격을 만들어가고 있어요. 이 환경에서는 파일 상단에 `version`을 아예 쓰지 않아도 도커가 똑똑하게 작동해요.

하지만 주의할 점이 있어요. 최신 환경이라고 해서 무조건 버전을 생략해도 된다는 뜻은 아니에요. 만약 여러분이 사용하는 환경이 CI/CD 파이프라인(예: Jenkins, GitHub Actions)을 통해 구축된다면, 빌드 환경의 도커 버전이 제각각일 수 있어요. 이럴 때는 명시적으로 버전을 적어주는 것이 환경 간의 격차를 줄이는 가장 안전한 방법이에요.

💡 알아두기
가장 추천하는 방식은 현재 사용 중인 도커 엔진의 버전을 확인하고, 그 엔진이 지원하는 가장 높은 버전의 3.x 계열을 명시하는 것이에요. 예를 들어 도커 엔진이 최신이라면 `version: ‘3.8’`을 적는 것이 가장 무난해요.

STEP 4. 실무 적용을 위한 설정 옵션 해설

버전을 결정했다면 이제 실제 필드들을 채워 넣어야 해요. 버전별로 사용 가능한 옵션이 다르니 주의 깊게 봐야 해요. 아래는 실무에서 가장 자주 쓰이는 주요 옵션들이에요.

services: 실행할 컨테이너들의 집합이에요. 여기서 각 서비스의 이미지, 포트, 환경 변수를 설정해요.
networks: 컨테이너들이 서로 대화할 수 있는 통로를 만들어요. 버전 3에서는 Swarm 모드를 위한 오버레이(overlay) 네트워크 설정을 지원해요.
volumes: 컨테이너가 사라져도 데이터가 남도록 저장소를 연결해요.
deploy: 버전 3 이상에서만 사용 가능하며, 컨테이너의 복제본 개수(replicas)나 리소스 제한(CPU, Memory)을 설정할 때 사용해요.

STEP 5. 완성된 실무형 설정 예시 시나리오

이해를 돕기 위해 웹 서버와 데이터베이스를 함께 띄우는 표준적인 설정 예시를 보여드릴게요. 이 코드는 버전 3.8을 기준으로 작성되었으며, 실제 운영 환경에서 바로 응용할 수 있는 구조예요.

# docker-compose.yml 예시
version: '3.8'

services:
  web-app:
    image: nginx:latest
    ports:
      - "80:80"
    networks:
      - backend-net
    depends_on:
      - db-server
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

  db-server:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend-net

networks:
  backend-net:
    driver: bridge

volumes:
  db-data:

위 예시를 보면 `web-app` 서비스에 deploy 옵션을 사용하여 메모리 제한을 걸어두었어요. 이는 버전 3.8 이상의 기능을 활용한 것이며, 만약 버전 2를 사용했다면 이 부분에서 에러가 발생했을 거예요. 또한 `depends_on`을 통해 데이터베이스가 먼저 실행된 후 웹 서버가 뜨도록 순서를 제어하고 있죠. 이런 디테일이 모여 안정적인 서비스 운영을 가능하게 해요.

자주 하는 실수와 해결법 및 FAQ

실무에서 컴포즈 파일을 다루다 보면 예상치 못한 곳에서 문제가 터지곤 해요. 가장 흔하게 겪는 상황들을 정리했으니, 비슷한 문제를 겪고 있다면 바로 적용해 보세요.

자주 하는 실수와 해결법

❌ 실수: 버전 선언은 3.8인데, 사용 중인 도커 엔진이 너무 낮음
왜 발생하는가: 최신 문법을 썼지만, 실행 도구가 그 문법을 이해할 지식이 없는 상태예요.
✅ 해결법: docker version 명령어로 엔진 버전을 확인하고, 엔진을 업데이트하거나 파일의 버전을 낮추세요.

❌ 실수: 버전 2 파일에 ‘deploy’ 옵션을 넣음
왜 발생하는가: `deploy`는 버전 3부터 도입된 스위머(Swarm)용 기능이라 버전 2 엔진은 이를 무시하거나 에러를 냅니다.
✅ 해결법: Swarm 기능을 쓰고 싶다면 파일 상단의 버전을 `version: ‘3’` 이상으로 올리세요.

❌ 실수: docker-compose 명령어가 작동하지 않음
왜 발생하는가: 최신 도커는 `docker-compose`(하이픈 포함) 대신 `docker compose`(공백) 명령어를 기본으로 사용해요.
✅ 해결법: 명령어에서 하이픈을 빼고 docker compose up으로 입력해 보세요.

❌ 실수: 환경 변수 설정 파일(.env)을 못 읽어옴
왜 발생하는가: 컴포즈 파일과 같은 경로에 `.env` 파일이 없거나 파일명이 잘못되었을 때 발생해요.
✅ 해결법: 파일 위치를 확인하고, 필요하다면 `–env-file` 옵션으로 경로를 직접 지정하세요.

❌ 실수: 볼륨 연결 후 데이터가 사라짐
왜 발생하는가: 버전 설정 문제라기보다, 볼륨(volumes)을 명시하지 않고 컨테이너 내부 경로에만 저장했기 때문이에요.
✅ 해결법: 반드시 파일 하단의 `volumes` 섹션에 이름을 등록하고 서비스와 연결하세요.

자주 묻는 질문

Q. 컴포즈 파일 맨 위에 버전을 꼭 써야 하나요?

최신 도커 컴포즈 V2를 사용 중이고 아주 단순한 설정이라면 생략해도 동작해요. 하지만 협업 환경이나 자동화 도구(CI/CD)를 사용할 때는 명확한 규격을 위해 적어주는 것이 훨씬 안전해요.

Q. 버전 3.8이 버전 3.0보다 무조건 좋은 건가요?
숫자가 높을수록 더 많은 최신 기능과 수정된 문법을 지원한다는 뜻이에요. 따라서 사용 중인 도커 엔진이 지원한다면 높은 버전을 쓰는 것이 좋습니다.

Q. 버전 2와 3 중 무엇을 선택해야 할지 모르겠어요.
대부분의 현대적인 프로젝트는 버전 3를 권장해요. 특히 나중에 서버를 늘리거나 클라우드 환경으로 옮길 계획이 있다면 고민하지 말고 버전 3를 선택하세요.

Q. 버전 번호를 잘못 적으면 어떻게 되나요?
도커 엔진이 해당 버전을 지원하지 않으면 실행 단계에서 바로 에러 메시지를 띄우며 중단돼요. 시스템 자체가 망가지는 일은 없으니 안심하고 수정하면 돼요.

Q. 버전 3에서 네트워크 설정이 왜 버전 2보다 복잡해 보이죠?
버전 3는 여러 대의 서버를 연결하는 ‘오버레이 네트워크’를 지원하기 위해 설계되었기 때문이에요. 단일 서버라면 버전 2의 ‘브리지(bridge)’ 방식이 더 직관적일 수 있어요.

컴포즈 버전 마스터를 위한 마지막 체크리스트

오늘 배운 내용을 바탕으로 여러분의 컴포즈 파일을 다시 한번 점검해 보세요. 복잡한 이론보다 중요한 것은 실제로 에러 없이 컨테이너를 띄우는 실무적인 감각이에요.

✅ 핵심 요약

파일 상단의 버전은 엔진에게 문법을 알려주는 약속이에요.
단일 서버 위주라면 버전 2, 확장성과 Swarm이 중요하다면 버전 3를 선택하세요.
최신 환경에서는 버전 숫자를 생략하는 ‘Compose Spec’ 방식이 대세예요.
`deploy` 같은 특정 기능은 반드시 지정된 버전 이상에서만 작동해요.
명령어 입력 시 `docker compose`(공백)를 사용하는 습관을 들이세요.

이제 여러분은 컴포즈 파일의 버전을 보고 이 파일이 어떤 환경을 타깃으로 작성되었는지 파악할 수 있는 눈을 갖게 되었어요. 처음에는 헷갈릴 수 있지만, 직접 에러 메시지를 마주하며 버전을 바꿔보는 과정이 가장 빠른 학습 방법이에요.

오늘 바로 실천해 보세요!
지금 운영 중인 프로젝트의 docker-compose.yml 파일을 열어보세요. 그리고 상단의 버전이 현재 사용 중인 도커 엔진 버전과 잘 맞는지, 혹은 너무 오래된 방식은 아닌지 확인해 보는 것부터 시작해 보세요. 설정 예시를 그대로 복사해 테스트 서버에서 먼저 실행해 보는 것도 아주 좋은 방법이에요.

더 깊이 있는 도커 운영 기술을 익히고 싶다면, 다음 주제인 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 읽어보시는 것을 추천드려요. 컨테이너 네트워크와 볼륨 관리까지 함께 공부하면 여러분의 인프라 구축 능력은 한 층 더 성장할 거예요.