[IT-방법] docker compose yml 시작하기 가이드 – 설치부터 첫 실행까지 30분 안에 끝내는 실습 과정

왜 수동으로 컨테이너를 하나씩 실행하고 계신가요

어제까지만 해도 잘 돌아가던 서버가 갑자기 멈췄을 때, 터미널을 열고 수십 줄에 달하는 docker run 명령어를 하나씩 복사해서 붙여넣고 계시진 않나요? 네트워크 설정을 어떻게 했는지, 볼륨 경로는 어디였는지 기억이 가물가물해서 명령어를 틀릴 때마다 느끼는 그 막막함은 모든 주니어 개발자가 한 번쯤 겪는 통과의례와 같아요. 컨테이너가 한두 개일 때는 상관없지만, 데이터베이스와 웹 서버, 캐시 서버까지 얽히기 시작하면 명령어를 관리하는 것 자체가 엄청난 스트레스가 되죠.

이런 혼란을 해결해 주는 구원투수가 바로 도커 컴포즈(Docker Compose)예요. 복잡한 실행 옵션들을 하나의 파일에 예쁘게 정리해 두고, 명령어 딱 한 줄로 모든 서비스를 동시에 띄울 수 있거든요. docker-compose.yml 파일 하나만 있으면, 마치 마법처럼 설계도에 그려진 대로 인프라가 구축되는 경험을 할 수 있어요. 이제 더 이상 메모장에 명령어를 적어두고 씨름할 필요가 없답니다.

이 글을 끝까지 읽고 나면, 여러분은 단순히 명령어를 외우는 수준을 넘어 docker compose yml 시작하기의 핵심 원리를 이해하게 될 거예요. 설정 파일의 구조를 파악하고, 실제 작동하는 환경을 구축하며, 발생할 수 있는 오류까지 스스로 해결할 수 있는 능력을 갖추게 됩니다. 딱 30분만 투자해 보세요. 여러분의 개발 환경이 훨씬 깔끔해질 거예요.

실습 전 반드시 갖춰야 할 준비물과 체크리스트

본격적으로 파일을 작성하기 전에, 여러분의 컴퓨터가 준비되었는지 확인해야 해요. 도커 컴포즈는 독립적으로 작동하는 도구가 아니라, 도커 엔진(Docker Engine) 위에서 돌아가는 관리 도구이기 때문이에요. 엔진이 없다면 아무리 완벽한 YAML 파일을 써도 무용지물이죠. 또한, 최근에는 도커 설치 시 컴포즈 기능이 기본적으로 포함되는 추세지만, 구버전을 사용 중이라면 별도의 설치 과정이 필요할 수도 있어요.

가장 먼저 확인해야 할 것은 현재 설치된 도커의 버전이에요. 터미널이나 명령 프롬프트를 열고 명령어를 입력해 보세요. 만약 명령어를 찾을 수 없다는 메시지가 나온다면, 도커 데스크탑(Docker Desktop)을 먼저 설치해야 합니다. 운영체제에 따라 설치 방법이 조금씩 다르니 아래 비교 표를 참고해서 본인의 환경에 맞는 선택을 해보세요.

준비 과정에서 주의할 점이 있어요. 윈도우 사용자의 경우 반드시 WSL2(Windows Subsystem for Linux) 기반으로 도커를 설정하는 것을 강력하게 추천해요. 예전 방식인 Hyper-V 기반보다 훨씬 빠르고 안정적이거든요. 리눅스 사용자는 명령어를 입력할 때 sudo 권한이 필요할 수 있으니 미리 염두에 두세요.

환경 준비가 끝났다면, 이제 우리는 설계도 역할을 할 YAML(YAML Ain’t Markup Language) 형식을 마주할 준비가 된 거예요. YAML은 사람이 읽기 아주 편하게 만들어진 데이터 형식인데, 아주 작은 들여쓰기 실수 하나로 전체 시스템이 멈출 수 있는 예민한 친구이기도 하답니다. 하지만 걱정 마세요. 하나씩 차근차근 맞춰가면 되니까요.

설계도를 작성하고 첫 컨테이너를 띄우는 5단계 실습

이제 진짜 실전이에요. 우리는 아주 간단하지만 실무에서 가장 많이 쓰이는 구조인 Nginx 웹 서버를 띄워볼 거예요. 이 과정을 통해 docker-compose.yml의 핵심 문법을 자연스럽게 익힐 수 있습니다. 눈으로만 보지 말고, 꼭 직접 타이핑하며 따라 해 보세요.

STEP 1. 작업 디렉터리 생성과 버전 확인하기

먼저 프로젝트를 담을 깨끗한 폴더를 만들어야 해요. 터미널을 열고 아래 명령어를 입력해 보세요. 폴더 이름은 자유롭지만, 연습을 위해 my-web-server로 정할게요.

mkdir my-web-server && cd my-web-server

폴더에 들어왔다면, 우리가 사용할 도구가 제대로 설치되었는지 확인해야겠죠? docker compose version 명령어를 입력해 보세요. 버전 정보가 출력된다면 준비 완료입니다. 만약 명령어가 작동하지 않는다면 도커 엔진이 실행 중인지 먼저 확인해 주세요.

STEP 2. docker-compose.yml 파일 생성하기

이제 프로젝트의 심장인 파일을 만들 차례예요. 텍스트 에디터(VS Code 추천)를 사용하여 폴더 안에 docker-compose.yml이라는 이름의 파일을 생성하세요. 확장자가 .yaml이 아닌 .yml이어도 괜찮지만, 관습적으로 .yml을 가장 많이 사용한답니다.

파일을 만들었다면, 일단은 빈 화면으로 두세요. 다음 단계에서 하나씩 채워나갈 거예요.

STEP 3. 핵심 문법을 담은 설계도 작성하기

이제 본격적으로 내용을 채워볼게요. 아래의 코드를 복사해서 파일에 붙여넣어 보세요. 하지만 단순히 복사하기보다는, 각 줄이 무엇을 의미하는지 반드시 이해해야 합니다.

services:
  web-server:
    image: nginx:latest
    ports:
      - "8080:80"
    environment:
      - TZ=Asia/Seoul

작성한 코드가 어떤 의미를 갖는지 자세히 뜯어볼까요?

• services: 이 파일이 관리할 컨테이너들의 목록을 정의하는 시작점이에요.
• web-server: 우리가 임의로 붙인 컨테이너의 이름이에요. 이 이름은 나중에 로그를 확인하거나 컨테이너를 제어할 때 식별자로 쓰여요.
• image: nginx:latest: 컨테이너를 만들기 위한 설계도(이미지)를 지정해요. 여기서는 전 세계적으로 가장 많이 쓰이는 Nginx의 최신 버전을 가져오도록 설정했어요.
• ports: – “8080:80
  

  자주 하는 실수와 해결법

  처음 docker-compose.yml을 작성하다 보면 아주 사소한 실수 때문에 몇 시간씩 헤매는 경우가 생겨요. 가장 흔한 실패 사례들을 모아봤으니, 비슷한 상황에 처했다면 바로 적용해 보세요.

  • ❌ 실수: YAML 파일의 들여쓰기가 맞지 않아 에러가 발생함
    👉 왜 발생하는가: 탭(Tab) 문자를 섞어 썼거나, 스페이스 개수가 일치하지 않기 때문이에요.
    ✅ 해결법: 모든 들여쓰기를 스페이스 2칸으로 통일하고, 에디터의 ‘Render Whitespace’ 기능을 켜서 눈으로 확인하세요.
  • ❌ 실수: