[IT-정보] 컴포즈 파일 버전 기초 가이드 – 초보자도 실수 없이 설정하는 방법

갑자기 서버가 멈췄을 때 마주하는 당혹스러운 화면

어제까지만 해도 멀쩡하게 돌아가던 웹사이트가 갑자기 먹통이 되었어요. 급하게 로그를 확인해보니 “Unsupported config option”이라는 생소한 에러 메시지만 가득해요. 당황스러운 마음에 구글에 검색을 해보지만, 온통 영어로 된 복잡한 문서들뿐이라 어디서부터 손을 대야 할지 막막하기만 해요.

비전공자로 시작해서 갑자기 서버 운영 업무를 맡게 되었다면 이런 상황은 공포 그 자체예요. 분명히 남들이 짜놓은 코드를 그대로 복사해서 붙여넣었는데, 왜 내 컴퓨터에서는 작동하지 않는 걸까요? 범인은 바로 우리가 무심코 지나쳤던 컴포즈 파일 버전 설정에 있을 확률이 매우 높아요.

도커 컴포즈는 여러 개의 컨테이너를 하나의 세트로 묶어서 관리하는 아주 편리한 도구예요. 하지만 이 세트를 만드는 설명서인 YAML 파일 상단에 적힌 버전 정보가 내 컴퓨터의 도커 엔진과 맞지 않으면, 아무리 완벽한 코드라도 작동하지 않아요. 마치 최신형 게임 CD를 구형 게임기에 넣으려고 하는 것과 비슷해요.

이 글을 끝까지 읽고 나면, 더 이상 버전 설정 때문에 밤잠을 설칠 필요가 없어요. 컴포즈 파일의 구조를 이해하고, 내 환경에 딱 맞는 버전을 지정하는 법을 확실히 익히게 될 거예요. 오늘부터는 에러 메시지를 보고 겁먹는 대신, 차분하게 설정을 수정하는 프로 운영자의 모습을 갖추게 될 거예요.

오늘 함께 살펴볼 내용들

• 컴포즈 파일 버전이 의미하는 진짜 뜻
• 내 서버 환경에 맞는 버전 확인하는 법
• 실무에서 바로 쓰는 컴포즈 파일 작성 예제
• 자주 발생하는 설정 오류와 해결 방법

무작정 따라 하기 전에 꼭 알아야 할 기초 개념

컴포즈 파일을 작성하기 전에 우리가 사용하는 도구들이 서로 어떤 관계인지 먼저 이해해야 해요. 무턱대고 숫자를 적기보다는, 이 숫자가 어떤 역할을 하는지 아는 것이 중요해요. 도커 컴포즈(Docker Compose)는 여러 개의 컨테이너를 관리하는 지휘자라고 생각하면 편해요.

지휘자가 음악을 연주할 때 악보가 필요하듯, 도커 컴포즈도 YAML(YAML)이라는 형식의 파일로 명령을 받아요. 이때 파일 맨 윗줄에 적는 버전은 “이 악보가 어떤 규칙으로 쓰였는지”를 알려주는 약속이에요. 규칙이 다르면 지휘자가 악보를 읽지 못하고 연주를 멈춰버리거든요.

그렇다면 어떤 버전을 선택해야 할까요? 무조건 최신 버전이 좋다고 생각할 수 있지만, 실제로는 내 서버에 설치된 도커 엔진(Docker Engine)의 버전이 무엇인지가 훨씬 중요해요. 엔진은 낡았는데 악보는 최신식이라면 실행 자체가 안 되기 때문이에요.

버전별 주요 특징 비교

위 표를 보면 알 수 있듯이, 현재 우리가 가장 많이 사용하는 것은 3.x 버전대예요. 하지만 서버의 환경에 따라 선택 기준이 달라져야 한다는 점을 꼭 기억해 주세요. 무작정 최신 버전을 적기보다는, 내 서버가 어디까지 받아들일 수 있는지를 먼저 파악하는 것이 실력 있는 운영자의 자세예요.

컴포즈 파일 버전 기초 실전 적용하기

이제 이론은 접어두고 직접 파일을 만들어 볼 시간이에요. 단순히 코드를 타이핑하는 게 아니라, 각 줄이 어떤 의미를 갖는지 하나씩 뜯어보며 진행할게요. 이 과정을 거치면 나중에 코드가 길어져도 길을 잃지 않을 거예요.

STEP 1. YAML 파일의 기본 뼈대 잡기

모든 컴포즈 파일은 정해진 구조가 있어요. 가장 먼저 해야 할 일은 파일의 맨 윗줄에 버전을 명시하는 거예요. 예를 들어 version: '3.8'이라고 적는 식이죠. 이때 숫자 양옆에 작은따옴표를 붙여주는 것이 안전해요. 숫자로만 적으면 간혹 컴퓨터가 이를 숫자로 오해해서 형식이 깨지는 경우가 있거든요.

그다음에는 services라는 항목을 만들어야 해요. 이것은 “내가 실행하고 싶은 프로그램들의 목록”이라고 이해하면 쉬워요. 웹 서버, 데이터베이스, 캐시 서버 등을 이 아래에 하나씩 차곡차곡 쌓아 올리게 돼요.

STEP 2. 실제 서비스 구성 예제 (웹 + DB)

실제로 많이 쓰이는 구성인 웹 서버(Nginx)와 데이터베이스(MySQL) 조합을 만들어 볼게요. 아래 예제 코드를 눈으로 천천히 따라와 주세요.

version: '3.8'

services:
  web-server:
    image: nginx:latest
    ports:
      - "80:80"
    depends_on:
      - db-server

  db-server:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example_password

자, 이제 이 코드가 왜 이렇게 작성되었는지 세밀하게 살펴볼게요.
첫째, version: '3.8'은 우리가 사용할 규칙의 버전을 선언한 거예요.
둘째, services: 아래에 두 개의 서비스, 즉 web-server와 db-server를 정의했어요.

여기서 주의 깊게 볼 부분은 depends_on이에요. 이것은 “웹 서버가 켜지기 전에 데이터베이스부터 먼저 준비해줘”라는 명령이에요. 데이터베이스가 아직 준비되지 않았는데 웹 서버가 먼저 접속을 시도하면 에러가 나기 때문이죠. 이런 디테일이 서비스의 안정성을 결정해요.

STEP 3. 들여쓰기와 계급 구조 이해하기

많은 초보자가 실수하는 부분이 바로 계급 구조예요. YAML 파일은 들여쓰기를 통해 누가 누구의 밑에 속해 있는지를 결정해요. 위 예제에서 image:이나 ports:는 web-server의 설정값들이에요. 따라서 반드시 web-server보다 안쪽으로 들어가 있어야 해요.

만약 들여쓰기가 한 칸이라도 어긋나면, 컴퓨터는 image이 web-server의 설정인지, 아니면 전혀 다른 독립적인 서비스인지 구분하지 못해요. 그래서 작성 후에는 반드시 눈으로 계층 구조를 확인하는 습관을 가져야 해요.

STEP 4. 작성한 파일 실행하고 확인하기

파일을 다 만들었다면 이제 명령어를 날릴 차례예요. 터미널을 열고 파일이 있는 폴더로 이동한 뒤, docker-compose up -d라고 입력해 보세요. -d 옵션은 백그라운드에서 실행하라는 뜻이에요. 이 옵션을 빼면 터미널을 끄는 순간 서버도 같이 꺼져버리니 꼭 붙여주세요.

정상적으로 실행되었다면, docker ps 명령어를 통해 내가 만든 컨테이너들이 잘 떠 있는지 확인할 수 있어요. 만약 여기서 에러가 난다면, 아까 우리가 배운 버전 불일치나 들여쓰기 오류를 가장 먼저 의심해봐야 해요.

자주 하는 실수와 해결법

실무를 하다 보면 이론대로 되지 않는 순간이 훨씬 많아요. 특히 컴포즈 파일은 아주 작은 오타 하나로도 전체 시스템을 멈춰 세울 수 있어요. 가장 흔하게 발생하는 문제들을 모아봤으니, 비슷한 상황에 처했다면 바로 확인해 보세요.

• ❌ 버전 숫자를 잘못 적었을 때 → 왜 발생하는가: 내 서버의 도커 엔진이 지원하지 않는 너무 높은 버전을 적었기 때문이에요. → ✅ 해결법: docker --version으로 엔진 버전을 먼저 확인하고, 그보다 낮은 버전을 선택하세요.
• ❌ 들여쓰기에 탭(Tab)을 사용했을 때 → 왜 발생하는가: YAML 규격은 탭 키를 허용하지 않아요. → ✅ 해결법: 모든 들여쓰기는 반드시 스페이스바(보통 2칸)로만 작성하세요.
• ❌ 버전 필드가 맨 위에 없을 때 → 왜 발생하는가: 컴포즈는 파일의 가장 처음에 규칙을 확인하려 하기 때문이에요. → ✅ 해결법: version: '3.8'을 파일의 가장 첫 줄로 옮겨주세요.
• ❌ 포트 번호 형식을 틀렸을 때 → 왜 발생하는가: 포트는 “호스트:컨테이너” 형식을 지켜야 해요. → ✅ 해결법: "80:80"처럼 따옴표를 사용하여 명확하게 표기하세요.
• ❌ 환경 변수 오타가 났을 때 → 왜 발생하는가: 데이터베이스 비밀번호 같은 중요한 설정이 틀리면 접속이 거부돼요. → ✅ 해결법: environment 섹션의 대소문자와 콜론(:) 위치를 다시 확인하세요.

자주 묻는 질문

Q. 컴포즈 파일 버전은 항상 최신으로 적는 게 좋지 않나요?

꼭 그렇지는 않아요. 최신 버전은 새로운 기능이 많지만, 그만큼 높은 사양의 도커 엔진을 요구해요. 서버 환경이 보수적이라면 안정적인 구버전을 사용하는 것이 오히려 운영 면에서는 더 유리할 수 있어요.

Q. 버전 필드를 아예 안 적으면 어떻게 되나요?

최신 버전의 도커 컴포즈(Compose V2)에서는 버전 필드를 생략해도 작동하도록 설계되어 있어요. 하지만 협업을 하거나 명확한 환경을 구축하고 싶다면, 명시적으로 버전을 적어주는 것이 나중에 발생할 문제를 예방하는 좋은 습관이에요.

Q. YAML 파일 작성이 너무 어려워요. 도구가 없을까요?

VS Code(Visual Studio Code) 같은 에디터를 사용해 보세요. YAML 확장 프로그램을 설치하면 들여쓰기가 틀렸을 때 빨간 줄로 바로 알려주기 때문에 실수를 획기적으로 줄일 수 있어요.

Q. docker-compose와 docker compose의 차이가 뭔가요?

하이픈(-)이 들어간 것은 예전 방식이고, 띄어쓰기를 한 것은 최신 방식이에요. 현재는 띄어쓰기를 하는 방식이 권장되지만, 대부분의 시스템에서 두 가지 모두 호환되도록 지원하고 있으니 크게 걱정하지 않으셔도 돼요.

성공적인 컨테이너 운영을 위한 마지막 정리

처음에는 복잡한 코드와 영어 메시지 때문에 막막할 수 있지만, 하나씩 원리를 깨우치다 보면 도커 컴포즈는 여러분의 가장 든든한 조력자가 될 거예요. 오늘 배운 핵심 내용을 잊지 않도록 다시 한번 짚어볼까요?

자, 이제 이론 공부는 충분해요. 이제 직접 터미널을 열고 아주 간단한 Nginx 서버부터 하나씩 띄워보면서 손에 익히는 과정이 필요해요. 이해가 잘 안 되는 용어가 있다면 그냥 넘기지 말고, 직접 명령어를 입력하며 에러를 마주해 보세요. 그 에러를 해결하는 순간이 여러분의 실력이 가장 크게 성장하는 때니까요.

오늘 바로 실행해 볼 일은 무엇일까요? 지금 바로 사용 중인 서버의 도커 버전을 확인하고, 기존에 쓰던 컴포즈 파일의 버전이 적절한지 검토해 보세요. 이번 주에는 아주 간단한 2계층 구조(웹+DB)의 컴포즈 파일을 직접 처음부터 끝까지 작성해 보는 것을 목표로 삼아보세요.

컴포즈 파일 설정에 대해 더 깊이 알고 싶다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 참고해 보시는 것도 큰 도움이 될 거예요.