[IT-정보] 도커 컴포즈 질문 정리 완벽 가이드 – 입문 개발자가 가장 헷갈려 하는 핵심 설정과 명령어 해결

도커 컴포즈, 왜 매번 명령어가 헷갈릴까요?

도커 컨테이너를 하나씩 띄우다 보면 어느 순간 명령어가 너무 길어져서 당황한 적이 있으시죠? 데이터베이스를 띄우고, 그 뒤에 웹 서버를 올리고, 설정 파일까지 연결하다 보면 터미널 창은 복잡한 명령어로 가득 차버려요. 명령어를 하나라도 틀리면 전체 서비스가 동작하지 않아 처음부터 다시 시작해야 하는 막막함도 느껴보셨을 거예요.

이런 혼란을 막아주는 것이 바로 도커 컴포즈(Docker Compose)예요. 여러 개의 컨테이너를 하나의 파일로 정의하고, 단 한 번의 명령어로 모두 실행할 수 있게 도와주는 아주 고마운 도구죠. 하지만 막상 사용하려고 하면 YAML 파일의 들여쓰기부터 네트워크 설정, 볼륨 연결까지 헷갈리는 부분이 한두 가지가 아니에요.

지금 이 글을 읽고 계신 여러분은 아마도 컨테이너를 효율적으로 관리하고 싶지만, 설정 과정에서 자꾸만 에러를 마주하는 입문 개발자일 확률이 높아요. 이 글을 끝까지 읽고 나면 더 이상 복잡한 명령어를 외울 필요가 없어요. 도커 컴포즈의 구조를 명확히 이해하고, 실무에서 자주 쓰이는 패턴을 익히게 될 거예요.

오늘 우리는 다음과 같은 내용을 함께 살펴볼 거예요.

• 도커 컴포즈를 시작하기 전 반드시 알아야 할 준비 사항
• 설정 파일(YAML) 작성 시 놓치기 쉬운 핵심 요소들
• 실무에서 바로 쓰는 실행 및 관리 명령어 패턴
• 자주 발생하는 오류와 운영 중 생기는 궁금증 해결

도커 컴포즈 시작 전, 이것만은 체크하세요

도커 컴포즈를 본격적으로 다루기 전에 먼저 내 컴퓨터 환경이 준비되었는지 확인해야 해요. 아무리 좋은 설정 파일을 만들어도 엔진이 없거나 버전이 맞지 않으면 무용지물이기 때문이죠. 특히 최근에는 도커 엔진에 컴포즈 기능이 내장되는 추세라 버전 확인이 아주 중요해요.

필수 준비물과 환경 체크리스트

가장 먼저 도커 엔진(Docker Engine)이 설치되어 있어야 해요. 그리고 본인이 사용 중인 도커 버전이 컴포즈를 지원하는지 확인해야 하죠. 최신 버전의 도커 데스크탑을 사용하고 있다면 대부분 문제없지만, 리눅스 서버 환경이라면 별도로 플러그인을 설치해야 할 수도 있어요.

도커 단독 사용 vs 도커 컴포즈 비교

도커 컴포즈를 왜 써야 하는지 감이 잘 안 온다면, 아래 표를 통해 차이점을 확인해 보세요. 단순한 비교를 넘어, 왜 우리가 컴포즈로 넘어가야 하는지 그 기준을 알 수 있어요.

표에서 볼 수 있듯이, 서비스가 2개 이상으로 늘어나는 순간 도커 컴포즈는 선택이 아닌 필수적인 도구가 돼요. 특히 협업할 때 팀원들에게

도커 컴포즈 핵심 설정과 단계별 실행 가이드

도커 컴포즈의 심장은 바로 docker-compose.yml 파일이에요. 이 파일 하나에 우리가 운영할 모든 인프라의 설계도가 담기죠. 설정을 잘못하면 컨테이너끼리 서로 대화를 못 하거나, 데이터가 자고 일어나면 사라지는 대참사가 벌어질 수 있어요. 차근차근 단계를 밟아 나가며 제대로 된 설계도를 그리는 법을 배워볼게요.

STEP 1. YAML 파일의 기본 구조 잡기

YAML(YAML Ain’t Markup Language)은 읽기 쉽지만, 아주 까다로운 규칙이 하나 있어요. 바로 들여쓰기(Indentation)예요. 탭(Tab)을 사용하면 에러가 날 확률이 높으니, 반드시 스페이스(Space) 2칸 혹은 4칸으로 통일해서 사용해야 해요.

기본적인 구조는 다음과 같이 구성돼요.

• services: 실행할 컨테이너들의 목록을 정의해요.
• networks: 컨테이너들이 통신할 가상의 네트워크를 설정해요.
• volumes: 데이터를 영구적으로 저장할 공간을 정의해요.

가장 핵심인 services 아래에는 각 서비스의 이름(예: web, db, cache)을 적고, 그 아래에 이미지 종류, 포트 설정, 환경 변수 등을 계층적으로 나열하게 돼요. 이 계층 구조를 눈으로 잘 익혀두는 것이 첫걸음이에요.

STEP 2. 서비스별 상세 속성 이해하기

각 서비스 내부에는 다양한 옵션을 넣을 수 있어요. 자주 쓰이는 4가지 핵심 속성을 꼭 기억하세요.

1. image: 사용할 컨테이너 이미지를 지정해요. 예를 들어 mysql:8.0처럼 버전을 명시하는 것이 안전해요.
2. ports: 호스트와 컨테이너의 포트를 연결해요. "8080:80"이라고 적으면, 내 컴퓨터의 8080번 포트로 들어온 요청을 컨테이너 내부의 80번 포트로 보내줘요.
3. environment: 데이터베이스 비밀번호나 API 키 같은 환경 변수를 설정해요.
4. depends_on: 서비스 간의 실행 순서를 정해요. 예를 들어 웹 서버가 DB보다 먼저 뜨면 에러가 나니까, 웹 서버 설정에 depends_on: [db]를 추가하는 식이에요.

STEP 3. 네트워크와 볼륨으로 연결성 확보하기

컨테이너를 띄웠는데 서로 통신을 못 한다면 네트워크 설정을 의심해야 해요. 도커 컴포즈는 기본적으로 하나의 프로젝트를 위한 전용 네트워크를 자동으로 만들어줘요. 덕분에 웹 서버에서 데이터베이스에 접속할 때 IP 주소가 아닌 서비스 이름(예: db)만으로도 접근할 수 있는 마법이 가능해져요.

데이터 보존을 위한 볼륨(Volumes) 설정도 매우 중요해요. 컨테이너는 삭제되면 내부 데이터도 함께 사라지거든요. 그래서 데이터베이스의 데이터 파일 같은 것은 반드시 호스트의 폴더나 도커가 관리하는 명명된 볼륨(Named Volume)에 연결해 두어야 해요. 이렇게 해야 컨테이너를 재시작하거나 업데이트해도 데이터가 안전하게 유지돼요.

STEP 4. 실전 시나리오: 웹 서버와 데이터베이스 조합

이론만으로는 부족하죠? 실제 현업에서 가장 많이 사용하는 웹 서버(Node.js) + 데이터베이스(PostgreSQL) 조합의 설정 예시를 살펴볼게요. 이 흐름을 이해하면 어떤 복잡한 조합도 만들 수 있어요.

# docker-compose.yml 예시
version: '3.8'
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: mypassword
    volumes:
      - db_data:/var/lib/postgresql/data
web:
    build: .
    ports:
      "3000:3000"
    depends_on:
      - db
networks:
  default:
    driver: bridge
volumes:
  db_data:

위 설정에서 web 서비스는 현재 디렉토리(.)의 Dockerfile을 이용해 직접 빌드하고, db 서비스가 준비될 때까지 기다렸다가 실행돼요. 데이터는 db_data라는 볼륨에 안전하게 저장되죠. 이 구조가 바로 현대적인 마이크로서비스의 가장 기초적인 형태예요.

STEP 5. 명령어 실행과 관리의 기술

설정 파일을 다 만들었다면 이제 명령어로 명령을 내려야 해요. 가장 많이 쓰는 명령어들을 상황별로 정리해 드릴게요.

• 서비스 전체 시작: docker compose up -d (뒤에 -d를 붙여야 백그라운드에서 조용히 실행돼요.)
• 서비스 전체 중지 및 삭제: docker compose down (컨테이너뿐만 아니라 네트워크까지 깔끔하게 정리해 줘요.)
• 로그 확인: docker compose logs -f (실시간으로 컨테이너가 뭐라고 하는지 보고 싶을 때 필수예요.)
• 컨테이너 내부 접속: docker compose exec web bash (실행 중인 웹 컨테이너 안으로 직접 들어가서 명령어를 치고 싶을 때 써요.)

이 명령어들만 손에 익어도 도커 컴포즈 운영의 절반은 성공한 셈이에요. 이제 실수를 줄이고 운영의 안정성을 높이는 방법을 알아볼까요?

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

도커 컴포즈를 사용하다 보면 분명히 맞게 쓴 것 같은데 에러가 터지는 순간이 있어요. 그럴 때마다 당황하지 말고 아래의 패턴들을 확인해 보세요. 대부분의 문제는 여기서 해결돼요.

자주 하는 실수와 해결법

• ❌ 실수: YAML 파일의 들여쓰기 오류
  왜 발생하는가: 탭(Tab) 문자를 섞어 썼거나 스페이스 개수가 맞지 않아서 문법 오류가 발생해요.
  ✅ 해결법: 반드시 스페이스 2칸 혹은 4칸으로 통일하고, VS Code 같은 에디터의 YAML 확장 프로그램을 사용해 들여쓰기를 시각적으로 확인하세요.
• ❌ 실수: 포트 충돌 발생
  왜 발생하는가: 호스트 컴퓨터에서 이미 사용 중인 포트를 ports 항목에 지정했기 때문이에요.
  ✅ 해결법: "8080:80"에서 앞의 숫자(8080)를 다른 번호로 바꾸어 보세요.
• ❌ 실수: 컨테이너 간 통신 불가
  왜 발생하는가: 서로 다른 네트워크에 속해 있거나 서비스 이름을 잘못 적었을 때 발생해요.
  ✅ 해결법: 같은 프로젝트 내의 서비스라면 서비스 이름을 호스트 이름으로 사용할 수 있어요. db 서비스라면 http://db:5432 형태로 접속하세요.
• ❌ 실수: 데이터가 자꾸 사라짐
  왜 발생하는가: 컨테이너 내부 경로에만 파일을 저장하고 볼륨 설정을 하지 않았기 때문이에요.
  ✅ 해결법: volumes 설정을 통해 호스트 폴더나 명명된 볼륨을 반드시 연결해 주세요.
• ❌ 실수: 코드 수정이 반영되지 않음
  왜 발생하는가: 이미 빌드된 이전 이미지(캐시)를 계속 사용하고 있기 때문이에요.
  ✅ 해결법: docker compose up --build 명령어를 사용하여 이미지를 새로 빌드하며 실행하세요.

자주 묻는 질문

Q. docker-compose와 docker compose의 차이는 무엇인가요?

둘은 거의 같지만 기술적으로는 달라요. 예전에는 별도의 도구였던 docker-compose(하이픈 있음)가 현재는 도커 엔진의 플러그인 형태로 통합되어 docker compose(하이픈 없음)로 쓰여요. 최신 환경에서는 하이픈 없는 명령어를 권장해요.

Q. 특정 컨테이너 하나만 재시작하고 싶을 때는 어떻게 하나요?

전체를 다 끄지 않고 docker compose restart [서비스이름] 명령어를 사용하면 해당 서비스만 깔끔하게 다시 시작할 수 있어요.

Q. 설정 파일 이름을 docker-compose.yml이 아닌 다른 걸로 쓰고 싶어요.

가능해요! docker compose -f my-config.yml up처럼 -f 옵션을 사용하여 원하는 파일 이름을 직접 지정해 주면 돼요.

Q. 환경 변수를 따로 관리하는 가장 좋은 방법은 무엇인가요?

.env 파일을 만드는 것이 가장 좋아요. .env 파일에 변수들을 적어두면 도커 컴포즈가 자동으로 읽어서 environment 섹션에 적용해 준답니다.

Q. 컨테이너가 계속 죽는데 이유를 어떻게 알 수 있나요?

가장 빠른 방법은 docker compose logs [서비스이름]을 입력하는 거예요. 서비스가 종료되기 직전에 남긴 에러 메시지를 통해 무엇이 문제인지 즉시 파악할 수 있어요.

도커 컴포즈 마스터를 위한 마지막 정리

도커 컴포즈는 처음에는 복잡해 보일 수 있지만, 한 번 익숙해지면 인프라 관리가 얼마나 편해지는지 몸소 느끼게 될 거예요. 명령어를 일일이 치는 수고를 덜어주고, 팀원들과 동일한 환경을 공유할 수 있게 해주니까요. 오늘 배운 내용을 바탕으로 작은 프로젝트부터 하나씩 적용해 보세요.

오늘 공부한 내용이 실제 개발 환경을 구축하는 데 큰 도움이 되었기를 바라요. 만약 실습 중에 도저히 풀리지 않는 에러 메시지를 만났다면, 주저하지 말고 댓글로 남겨 주세요. 여러분이 겪은 문제를 함께 고민하고 답변을 정리해 추가하도록 할게요.

🚀 다음 단계로 나아가기:

• 오늘 할 일: 간단한 Nginx 컨테이너를 띄우는 docker-compose.yml 작성해 보기
• 이번 주 할 일: DB와 웹 서버를 연결하는 다중 컨테이너 환경 구축해 보기
• 실행 직전 할 일: 환경 변수(.env)를 활용해 보안 설정 적용해 보기

관련해서 더 깊이 있는 개념이 궁금하다면 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글을 함께 읽어보시는 것을 추천해요.