[IT-정보] 도커 컴포즈 기초 완벽 가이드 – 복잡한 컨테이너 설정을 한 번에 해결하는 실무 방법

도커 컴포즈가 왜 필요한가요? 혼란스러운 컨테이너 세상에서 살아남기

어제까지는 분명히 잘 돌아가던 서버였어요. 그런데 오늘 아침, 새로운 기능을 추가하려고 컨테이너를 하나 더 띄웠더니 갑자기 데이터베이스 연결이 끊기고 웹 사이트가 먹통이 되어버렸어요. 당황스러운 마음에 터미널을 열고 수십 줄의 docker run 명령어를 하나씩 입력해 보지만, 어떤 옵션을 썼는지, 포트 번호는 무엇이었는지 기억이 나지 않아 머릿속이 하얘지는 경험을 해본 적이 있나요?

비전공자 출신으로 갑자기 서버 운영을 맡게 되었다면 이런 상황은 공포 그 자체일 거예요. 컨테이너 하나를 띄우는 건 쉽지만, 웹 서버, 데이터베이스, 캐시 서버처럼 서로 연결되어야 하는 여러 개의 컨테이너를 동시에, 그리고 올바르게 관리하는 건 완전히 다른 차원의 문제거든요. 명령어 하나만 잘못 입력해도 전체 시스템이 엉망이 될 수 있어요.

이런 혼란을 잠재우고 우리를 구원해 줄 도구가 바로 도커 컴포즈(Docker Compose)예요. 도커 컴포즈는 여러 개의 컨테이너를 하나의 설계도에 담아, 마치 마법처럼 한 번에 실행하고 관리할 수 있게 도와주는 아주 고마운 도구랍니다. 일일이 명령어를 외울 필요 없이, 파일 하나에 모든 설정을 적어두기만 하면 돼요.

이 글을 끝까지 읽고 나면, 복잡한 명령어 더미에서 벗어나 깔끔하게 정리된 설정 파일로 서버를 운영하는 즐거움을 느끼게 될 거예요. 우리는 다음과 같은 내용을 차근차근 살펴볼 거예요.

• 도커 컴포즈를 이해하기 위한 필수 용어 정리
• 도커와 도커 컴포즈의 결정적인 차이점
• 실제로 작동하는 설정 파일 작성법과 실행 단계
• 실무에서 자주 발생하는 실수와 해결 방법

시작 전 반드시 알아야 할 핵심 용어와 준비물

본격적으로 도커 컴포즈를 다루기 전에, 최소한의 언어는 통해야겠죠? 마치 외국 여행을 떠나기 전 기초 회화를 배우는 것과 같아요. 용어를 모르면 설명서를 읽어도 무슨 뜻인지 알 수 없으니까요.

꼭 알아야 할 4가지 핵심 개념

가장 먼저 만날 단어들은 서비스(Service), 이미지(Image), 컨테이너(Container), 그리고 볼륨(Volume)이에요. 이 단어들이 어떻게 연결되는지 이해하는 것이 첫걸음이에요.

• 이미지(Image): 컨테이너를 만들기 위한 설계도나 붕어빵 틀이라고 생각하면 쉬워요. 프로그램 실행에 필요한 모든 것이 들어있어요.
• 컨테이너(Container): 이미지를 실행시킨 실제 상태예요. 붕어빵 틀에서 찍어낸 실제 붕어빵이라고 할 수 있죠.
• 서비스(Service): 도커 컴포즈에서 컨테이너를 정의하는 단위예요. “웹 서버 서비스”, “DB 서비스”처럼 역할을 부여하는 것이죠.
• 볼륨(Volume): 컨테이너가 사라져도 데이터는 남아야 하죠? 데이터를 저장하는 별도의 저장 공간을 말해요.

도커와 도커 컴포즈, 무엇이 다른가요?

많은 분이 이 두 가지를 혼동하곤 해요. 간단히 말하면 도커는 개별 일꾼이고, 도커 컴포즈는 그 일꾼들에게 역할을 나누어주고 지휘하는 감독관이에요.

따라서 규모가 작은 실험용이라면 도커만으로도 충분하지만, 실제 서버를 운영하거나 협업을 해야 한다면 도커 컴포즈는 선택이 아닌 필수라고 할 수 있어요.

도커 컴포즈로 컨테이너 환경 구축하기

이제 이론은 접어두고 직접 실습을 해볼 시간이에요. 우리는 가장 대중적인 조합인 Nginx(웹 서버)와 MariaDB(데이터베이스)를 연결하는 환경을 만들어볼 거예요. 이 과정만 완벽히 익히면 어떤 서비스든 구성할 수 있어요.

STEP 1. YAML 파일의 구조 이해하기

도커 컴포즈의 핵심은 docker-compose.yml이라는 파일이에요. 이 파일은 YAML(YAML Ain’t Markup Language)이라는 형식을 사용하는데, 아주 중요한 규칙이 하나 있어요. 바로 들여쓰기예요. 탭(Tab) 대신 스페이스(Space)를 사용해야 하며, 들여쓰기 칸수가 틀리면 파일 전체가 읽히지 않아요.

전체적인 구조는 크게 네 부분으로 나뉘어요.

• version: 사용하는 도커 컴포즈의 버전을 지정해요. 최근에는 생략하기도 하지만, 명시해 주는 것이 안전해요.
• services: 우리가 띄울 컨테이너들의 목록을 적는 곳이에요.
• networks: 컨테이너들이 서로 대화할 수 있는 통로를 정의해요.
• volumes: 데이터를 영구적으로 저장할 공간을 정의해요.

STEP 2. docker-compose.yml 작성하기

자, 이제 실제로 파일을 작성해 볼게요. 메모장이나 VS Code 같은 에디터를 열고 아래 내용을 그대로 따라 적어보세요. (물론 직접 타이핑하는 것을 강력히 추천해요! 그래야 눈에 익거든요.)

# 도커 컴포즈 설정 파일 예시
version: '3.8'

services:
  # 1. 데이터베이스 서비스
  db-server:
    image: mariadb:10.6
    container_name: my_database
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: password123
      MYSQL_DATABASE: my_app_db
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - app_network

  # 2. 웹 서버 서비스
  web-server:
    image: nginx:latest
    container_name: my_web_server
    ports:
      - "8080:80"
    depends_on:
      - db-server
    networks:
      - app_network

# 데이터 저장을 위한 볼륨 정의
volumes:
  db_data:

# 컨테이너 간 통신을 위한 네트워크 정의
networks:
  app_network:

방금 작성한 코드의 의미를 하나씩 뜯어볼까요?
먼저 db-server 섹션을 보세요. image: mariadb:10.6은 MariaDB 10.6 버전을 사용하겠다는 뜻이에요. environment 부분은 데이터베이스를 처음 만들 때 필요한 비밀번호와 이름을 설정하는 아주 중요한 부분이죠. 특히 volumes에 적힌 db_data:/var/lib/mysql은 “내 컴퓨터의 db_data라는 공간을 컨테이너 안의 DB 저장 경로와 연결해라”라는 뜻이에요. 이렇게 해야 컨테이너를 삭제해도 데이터가 날아가지 않아요.

다음으로 web-server를 볼게요. ports: "8080:80"은 호스트(내 컴퓨터)의 8080번 포트로 접속하면 컨테이너 내부의 80번 포트로 연결해주라는 뜻이에요. 즉, 웹 브라우저에 localhost:8080을 입력하면 웹 서버에 접속할 수 있게 되는 거죠. 마지막으로 depends_on은 웹 서버가 켜지기 전에 데이터베이스가 먼저 준비되도록 순서를 정해주는 역할을 해요.

STEP 3. 명령어 실행하고 확인하기

파일을 저장했다면 이제 터미널(또는 명령 프롬프트)을 열고 해당 파일이 있는 폴더로 이동하세요. 그리고 다음 명령어를 입력해 보세요.

1) 서비스 실행하기:
docker-compose up -d
이 명령어를 치면 도커가 자동으로 이미지를 다운로드하고, 설정대로 컨테이너를 하나씩 띄워요. -d 옵션은 백그라운드에서 실행하라는 뜻이라서, 명령어를 입력한 후에도 터미널을 계속 사용할 수 있어요.

2) 상태 확인하기:
docker-compose ps
현재 어떤 컨테이너가 어떤 포트로 떠 있는지 한눈에 보여줘요. 만약 상태(Status)가 ‘Up’이 아니라면 문제가 생긴 거예요.

3) 로그 확인하기 (문제가 생겼을 때):
docker-compose logs -f
컨테이너 내부에서 어떤 일이 벌어지고 있는지 실시간으로 보여줘요. 에러 메시지를 찾는 가장 빠른 방법이에요.

STEP 4. 실전 운영 시나리오: 설정 변경하기

운영을 하다 보면 설정을 바꿔야 할 때가 반드시 와요. 예를 들어, 데이터베이스 비밀번호를 바꾸고 싶다면 어떻게 해야 할까요?
방법은 아주 간단해요. docker-compose.yml 파일에서 비밀번호 부분을 수정하고 다시 docker-compose up -d를 입력하기만 하면 돼요. 그러면 도커 컴포즈가 변경된 내용을 감지하고, 해당 컨테이너만 알아서 껐다 켜주며 설정을 반영해요. 일일이 수동으로 끄고 켤 필요가 없어서 정말 편리하죠.

자주 하는 실수와 해결법 및 자주 묻는 질문

처음에는 누구나 실수를 해요. 특히 도커 컴포즈는 설정 파일 하나에 모든 것이 담겨 있다 보니, 작은 실수 하나가 전체 시스템을 멈추게 할 수 있어요. 자주 발생하는 상황들을 미리 익혀두면 당황하지 않을 수 있어요.

자주 하는 실수와 해결법

• ❌ YAML 들여쓰기 오류 → YAML 파일은 칸수가 조금만 틀려도 인식을 못 해요.
  ✅ 해결법: 반드시 스페이스(Space)를 사용하고, VS Code 같은 에디터의 YAML 확장 프로그램을 설치해 들여쓰기 가이드를 눈으로 확인하세요.
• ❌ 포트 충돌(Port Conflict) → 이미 내 컴퓨터에서 8080 포트를 다른 프로그램이 쓰고 있다면 에러가 발생해요.
  ✅ 해결법: "8081:80"처럼 앞쪽 숫자를 다른 번호로 바꿔서 사용하세요.
• ❌ 데이터베이스 준비 미흡 → 웹 서버는 켜졌는데 데이터베이스가 아직 부팅 중이라 연결에 실패하는 경우예요.
  ✅ 해결법: depends_on을 사용하더라도 실제 DB가 준비될 때까지 시간이 걸릴 수 있어요. 애플리케이션 코드에서 ‘재시도(Retry) 로직’을 넣는 것이 가장 완벽해요.
• ❌ 볼륨 경로 설정 오류 → 컨테이너를 껐다 켰더니 데이터가 다 사라졌어요!
  ✅ 해결법: volumes 설정을 통해 데이터가 저장될 위치를 명확히 지정했는지, 그리고 호스트의 경로가 올바른지 다시 확인하세요.
• ❌ 환경 변수 오타 → 비밀번호를 맞게 적었다고 생각했는데 접속이 안 돼요.
  ✅ 해결법: environment 섹션의 대소문자와 콜론(:) 뒤의 공백을 확인하세요.

자주 묻는 질문

Q. 도커 컴포즈 파일 이름은 꼭 docker-compose.yml이어야 하나요?

아니요, 다른 이름으로 지을 수도 있어요. 하지만 명령어를 실행할 때 docker-compose -f my-config.yml up처럼 파일 이름을 직접 알려줘야 하는 번거로움이 있어요. 가급적 기본 이름을 사용하는 것을 추천해요.

Q. 컨테이너를 다 지우면 데이터도 같이 삭제되나요?

docker-compose down 명령어를 사용하면 컨테이너와 네트워크는 삭제되지만, 설정 파일의 volumes 섹션에서 정의한 데이터는 사라지지 않고 안전하게 유지돼요. 다만, 볼륨 자체를 삭제하는 명령어(-v 옵션)를 쓸 때는 주의해야 해요.

Q. 도커 컴포즈는 여러 대의 서버에 동시에 띄울 수 있나요?

도커 컴포즈는 기본적으로 한 대의 컴퓨터(호스트) 내에서 여러 컨테이너를 관리하도록 설계되었어요. 만약 여러 대의 서버를 묶어서 관리하고 싶다면, 도커 컴포즈의 상위 개념인 도커 스웜(Docker Swarm)이나 쿠버네티스(Kubernetes)를 공부해야 해요.

Q. 명령어 한 줄로 모든 걸 다 할 수 있나요?

네, docker-compose up -d 한 줄이면 이미지 다운로드, 네트워크 생성, 볼륨 생성, 컨테이너 실행까지 모든 과정이 자동으로 진행돼요. 이것이 도커 컴포즈를 쓰는 가장 큰 이유죠.

Q. 초보자가 공부하기에 가장 좋은 순서는 무엇인가요?

먼저 도커의 기본 명령어(run, ps, logs, stop)를 익힌 뒤, 오늘 배운 것처럼 도커 컴포즈로 여러 서비스를 묶어보는 연습을 하세요. 그다음 환경 변수와 볼륨을 깊게 파고드는 순서가 가장 효율적이에요.

이제 당신도 컨테이너 오케스트레이션을 시작할 수 있어요

처음에는 검은 화면에 나타나는 영어 명령어들이 낯설고 무섭게 느껴질 수 있어요. 하지만 도커 컴포즈라는 든든한 조수와 함께라면, 복잡한 서버 환경도 한 장의 설계도로 깔끔하게 통제할 수 있답니다. 오늘 배운 내용을 바탕으로 하나씩 직접 실행해 보는 것이 가장 중요해요.

이해되지 않는 용어나 에러 메시지가 있다면 절대 그냥 넘어가지 마세요. 직접 코드를 타이핑하고, 일부러 오타를 내보기도 하면서 에러를 마주하는 과정이 진짜 실력을 만들어준답니다.

오늘 바로 실천할 계획표

• 오늘 할 일: 도커 컴포즈 설치 확인 및 docker-compose version 명령어로 버전 체크하기
• 이번 주 할 일: 위에서 배운 Nginx와 MariaDB 예제를 직접 작성하고 실행해 보기
• 실행 직전 할 일: YAML 파일의 들여쓰기 실수를 방지하기 위해 에디터 설정 확인하기

도커 컴포즈에 익숙해졌다면, 다음 단계로는 컨테이너의 상태를 더 세밀하게 관리하는 법이나 실제 클라우드 환경(AWS 등)에 배포하는 방법을 알아보는 것을 추천해요.

관련해서 더 깊이 있는 내용이 궁금하시다면 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글을 함께 읽어보세요. 여러분의 서버 운영 여정을 진심으로 응원할게요!