왜 지금 컴포즈 services 시작하기가 필요할까요?
터미널 창을 열고 길고 복잡한 docker run 명령어를 하나씩 입력하다가 결국 오타를 내고 멈춰버린 경험이 있으신가요? 데이터베이스를 띄우고, 그 위에 웹 서버를 올리고, 캐시 서버까지 연결해야 하는데 명령어가 꼬이기 시작하면 정말 눈앞이 캄캄해지곤 해요. 컨테이너 하나를 실행하는 것은 쉽지만, 이들을 하나의 서비스로 묶어서 관리하는 순간부터는 차원이 다른 복잡함이 찾아오거든요.
특히 주니어 개발자라면 여러 개의 컨테이너가 서로 어떤 포트로 연결되어 있는지, 볼륨은 어디에 마운트했는지 일일이 기억하는 것이 불가능에 가깝다는 걸 깨닫게 돼요. 동료 개발자가 만든 환경을 내 컴퓨터에 똑같이 재현하려고 해도, 명령어를 하나라도 빼먹으면 서비스는 바로 작동을 멈추고 말아요. 이런 혼란을 해결해 주는 마법 같은 도구가 바로 도커 컴포즈예요.
도커 컴포즈를 사용하면 수많은 명령어를 하나의 파일로 정리할 수 있어요. services 블록이라는 공간에 우리가 원하는 모든 설정을 담아두기만 하면, 단 한 줄의 명령어로 전체 시스템을 완벽하게 들어 올릴 수 있답니다. 오늘 이 글을 끝까지 따라오시면, 복잡한 설정 없이도 여러분만의 컨테이너 환경을 스스로 구축하고 운영하는 기쁨을 맛보게 될 거예요.
도커 컴포즈는 여러 개의 컨테이너를 정의하고 실행하기 위한 도구예요. 설정 파일인 docker-compose.yml 파일에 모든 정보를 기록하므로, 팀원들과 환경을 공유하기 매우 편리해요.
이번 가이드에서는 다음의 내용들을 차근차근 다뤄볼 예정이에요.
- 컴포즈 실행을 위한 필수 환경 점검과 준비물
- 가장 핵심인 services 블록 작성법과 주요 옵션 이해
- 명령어 한 줄로 컨테이너를 실제로 띄우고 확인하는 방법
- 실행 과정에서 흔히 마주치는 오류와 해결 방법
본격적인 시작 전, 꼭 확인해야 할 준비물과 기초 지식
컴포즈를 사용하기 위해서는 단순히 명령어를 아는 것보다, 현재 내 컴퓨터에 무엇이 설치되어 있고 어떤 개념을 잡고 있어야 하는지 아는 것이 훨씬 중요해요. 준비 없이 무작정 파일을 만들기 시작하면, 나중에 원인 모를 네트워크 오류나 권한 문제로 고생할 확률이 매우 높거든요.
필수 설치 환경 점검하기
가장 먼저 확인해야 할 것은 도커 엔진(Docker Engine)이 제대로 설치되어 있는지예요. 도커 컴포즈는 도커 엔진 위에서 동작하는 도구이기 때문에, 엔진이 없다면 컴포즈는 아무런 힘도 쓰지 못해요. 윈도우나 맥 사용자라면 Docker Desktop을 설치하는 것이 가장 빠르고 확실한 방법이에요. 리눅스 사용자라면 터미널에서 docker --version과 docker compose version 명령어를 입력해서 설치 여부를 꼭 확인해 주세요.
도커와 도커 컴포즈의 차이점 이해하기
많은 입문자가 도커와 도커 컴포즈를 혼동하곤 해요. 이 둘의 차이를 명확히 아는 것이 컨테이너 운영의 첫걸음이에요. 간단히 말하자면, 도커는 개별 컨테이너라는 ‘벽돌’을 만드는 도구이고, 도커 컴포즈는 그 벽돌들을 모아 ‘집’을 짓는 설계도와 같다고 생각하면 이해가 쉬워요.
| 비교 항목 | 도커 (Docker) | 도커 컴포즈 (Docker Compose) |
|---|---|---|
| 주요 목적 | 개별 컨테이너 생성 및 실행 | 여러 컨테이너의 통합 관리 |
| 설정 방식 | docker run 명령어 기반 |
YAML 파일(설계도) 기반 |
| 관리 단위 | 단일 컨테이너 | 서비스 그룹 (Multi-container) |
| 사용 편의성 | 복잡한 옵션 입력이 번거로움 | 파일만 수정하면 되어 매우 편리함 |
학습 전 체크리스트
실습을 시작하기 전에 아래 세 가지만 준비해 주세요. 이 준비물만 있다면 30분 안에 첫 서비스를 띄울 수 있어요.
- 텍스트 에디터: VS Code(Visual Studio Code)를 강력하게 추천해요. YAML 파일의 들여쓰기를 시각적으로 잘 보여주기 때문에 실수를 줄일 수 있거든요.
- 터미널 접근 권한: 명령어를 입력할 수 있는 터미널(PowerShell, iTerm2, Bash 등)이 준비되어 있어야 해요.
- 기본적인 네트워크 지식: IP 주소와 포트(Port) 번호가 무엇인지 아주 조금만 알고 있다면 훨씬 수월해요.
YAML 파일은 들여쓰기에 매우 민감해요. 탭(Tab) 대신 반드시 스페이스(Space)를 사용하여 들여쓰기를 해야 한다는 점을 꼭 기억해 주세요. 들여쓰기 하나만 틀려도 전체 설정이 무너질 수 있어요.
단계별 실행: 컴포즈 services 블록 구성부터 첫 실행까지
이제 준비는 끝났어요. 실제로 우리가 가장 많이 사용하게 될 docker-compose.yml 파일을 만들고, 그 안에 핵심인 services 블록을 채워 넣어볼게요. 이번 실습에서는 가장 대중적인 웹 서버인 Nginx를 띄워보는 시나리오로 진행할게요.
STEP 1. 작업 디렉터리 생성 및 파일 만들기
컴퓨터의 아무 곳에나 새로운 폴더를 하나 만들어 주세요. 예를 들어 my-first-compose라는 이름의 폴더를 만들고, 그 안으로 이동하세요. 그런 다음 에디터를 열어 docker-compose.yml이라는 이름의 파일을 생성해 주세요. 파일 이름이 정확하지 않으면 도커가 파일을 찾지 못하니 주의해야 해요.
STEP 2. services 블록의 뼈대 잡기
이제 파일 안에 내용을 채워 넣을 차례예요. 컴포즈 파일은 항상 전체 구조를 정의하는 최상위 키로 시작해야 해요. 가장 먼저 version을 적어주는데, 요즘은 버전을 명시하지 않아도 최신 표준을 따르지만, 명확성을 위해 '3.8' 정도를 적어주는 것이 관례예요. 그 아래에 우리가 실제 서비스를 정의할 services: 키를 작성합니다.
이 services 블록 아래에는 우리가 운영할 각각의 컨테이너 이름들을 나열하게 돼요. 여기서는 web-server라는 이름을 서비스 이름으로 정해볼게요. 이제 이 서비스가 어떤 이미지를 사용할지, 어떤 문을 열어둘지 결정해야 해요.
STEP 3. 핵심 설정 옵션 상세 구성하기
이제 가장 중요한 부분이에요. web-server 아래에 구체적인 설정을 추가해 볼게요. 이 옵션들은 컨테이너의 성격과 동작 방식을 결정하는 아주 중요한 요소들이에요.
- image: 어떤 소프트웨어를 설치할지 결정해요. 여기서는
nginx:latest를 사용해서 최신 버전의 Nginx를 가져올 거예요. - ports: 내 컴퓨터의 포트와 컨테이너의 포트를 연결해요.
'8080:80'이라고 적으면, 내 컴퓨터의 8080번 포트로 접속했을 때 컨테이너 안의 80번 포트로 연결된다는 뜻이에요. - environment: 컨테이너 내부에서 사용할 환경 변수를 설정해요. 예를 들어 데이터베이스 비밀번호 같은 정보를 안전하게 넘겨줄 때 사용하죠.
- volumes: 컨테이너의 데이터를 내 컴퓨터에 저장하고 싶을 때 사용해요. 컨테이너를 삭제해도 데이터가 사라지지 않게 보호해 주는 아주 고마운 기능이에요.
YAML 파일에서 들여쓰기는 계층 구조를 의미해요.
services 아래의 web-server는 한 단계 들여쓰고, web-server 아래의 image는 다시 한 단계 더 들여써야 해요. 이 규칙을 어기면 오류가 발생하니 조심하세요!STEP 4. 완성된 docker-compose.yml 코드 예시
앞서 설명한 내용을 종합하면 아래와 같은 코드가 완성됩니다. 이 코드를 그대로 복사해서 여러분의 파일에 붙여넣어 보세요.
version: '3.8'
services:
web-server:
image: nginx:latest
ports:
- "8080:80"
restart: always
environment:
- TZ=Asia/Seoul
여기서 restart: always 옵션도 추가했어요. 이 옵션을 넣으면 컴퓨터를 재부팅하거나 컨테이너가 갑자기 꺼졌을 때, 도커가 알아서 다시 서비스를 살려줘요. 실제 운영 환경에서는 매우 중요한 설정이랍니다.
STEP 5. 컨테이너 실행 및 동작 확인
이제 마법의 시간이에요! 터미널을 열고 파일이 있는 폴더로 이동한 뒤, 다음 명령어를 입력해 보세요.
docker compose up -d
여기서 -d 옵션은 detached mode를 의미해요. 이 옵션을 붙여야 컨테이너가 백그라운드에서 조용히 실행되고, 터미널을 계속 사용할 수 있어요. 명령어를 입력하고 잠시 기다리면 도커가 이미지를 내려받고 컨테이너를 생성하는 과정을 보여줄 거예요.
실행이 완료되었다면, 웹 브라우저를 열고 주소창에 localhost:8080을 입력해 보세요. 화면에 Welcome to nginx! 라는 문구가 보인다면, 여러분은 방금 첫 번째 서비스를 성공적으로 구축한 거예요! 정말 대단해요!
실습 결과 요약표
| 설정 항목 | 설정 값 | 의미 및 효과 |
|---|---|---|
| 서비스 이름 | web-server | 컴포즈 내에서 식별할 이름 |
| 사용 이미지 | nginx:latest | 최신 버전의 Nginx 소프트웨어 사용 |
| 포트 매핑 | 8080:80 | 외부 8080 포트를 통해 접속 허용 |
| 재시작 정책 | always | 장애 발생 시 자동 복구 실행 |
자주 하는 실수와 해결법 및 FAQ
성공적으로 서비스를 띄웠더라도, 실제 운영을 하다 보면 예상치 못한 벽에 부딪히기 마련이에요. 주니어 개발자들이 가장 많이 겪는 시행착오들을 정리했으니, 문제가 생기면 이 부분을 먼저 확인해 보세요.
자주 하는 실수와 해결법
- ❌ YAML 들여쓰기 오류 →
왜 발생하는가: 탭과 스페이스를 혼용하거나 들여쓰기 칸수가 맞지 않을 때 발생해요.
✅ 해결법: 반드시 스페이스 2칸 혹은 4칸으로 통일하고, VS Code의 YAML 확장 프로그램을 사용하여 구조를 눈으로 확인하세요. - ❌ 포트 충돌 오류 →
왜 발생하는가: 이미 내 컴퓨터의 8080번 포트를 다른 프로그램이 사용하고 있을 때 발생해요.
✅ 해결법:docker compose ps로 현재 사용 중인 포트를 확인하고, 설정 파일의 포트 번호를 8081이나 9000 등으로 변경해 보세요. - ❌ 이미지 다운로드 실패 →
왜 발생하는가: 인터넷 연결이 불안정하거나, 이미지 이름에 오타가 있을 때 발생해요.
✅ 해결법: 이미지 이름을 다시 확인하고,docker pull [이미지명]명령어로 이미지가 정상적으로 받아지는지 개별적으로 테스트해 보세요. - ❌ 컨테이너 데이터 증발 →
왜 발생하는가: 볼륨(volumes) 설정을 하지 않고 컨테이너를 삭제하면 데이터는 모두 사라져요.
✅ 해결법: 중요한 데이터(DB, 로그 등)는 반드시 volumes 설정을 통해 호스트 디렉터리와 연결해 두어야 해요. - ❌ 환경 변수 인식 불가 →
왜 발생하는가: 환경 변수 이름에 오타가 있거나 따옴표 처리가 잘못되었을 때 발생해요.
✅ 해결법: 환경 변수 형식이KEY=VALUE형태를 정확히 따르고 있는지 확인해 주세요.
자주 묻는 질문
Q. 실행 중인 컨테이너를 어떻게 멈추나요?
해당 디렉터리에서 docker compose stop 명령어를 입력하면 서비스가 중지돼요. 완전히 삭제하고 싶다면 docker compose down을 사용하면 됩니다.
Q. 설정 파일을 수정했는데 어떻게 적용하나요?
파일을 수정한 뒤 다시 docker compose up -d를 실행하면 돼요. 도커가 변경 사항을 감지해서 필요한 컨테이너만 알아서 다시 만들어준답니다.
Q. 로그를 실시간으로 보고 싶어요.
docker compose logs -f 명령어를 사용해 보세요. 컨테이너 내부에서 일어나는 일들을 실시간으로 확인할 수 있어 디버깅에 아주 유용해요.
Q. 여러 개의 서비스를 한 번에 띄울 수 있나요?
네, 당연하죠! services 블록 아래에 새로운 항목을 추가하기만 하면 됩니다. 예를 들어 Nginx 아래에 MySQL 서비스를 추가하여 웹 서버와 데이터베이스를 한꺼번에 실행할 수 있어요.
Q. 컨테이너가 자꾸 재시작(Restarting)만 반복해요.
컨테이너 내부에서 실행 중인 프로세스가 에러로 인해 종료되었을 가능성이 커요. docker compose logs를 통해 어떤 에러 메시지가 출력되고 있는지 반드시 확인해 보세요.
마무리하며: 이제 당신은 컨테이너 운영의 첫걸음을 뗐습니다
처음에는 낯선 명령어와 복잡해 보이는 YAML 파일이 어렵게 느껴질 수 있어요. 하지만 오늘 우리가 해본 것처럼, services 블록을 하나씩 채워나가다 보면 어느새 전체 인프라를 코드로 제어하는 자신을 발견하게 될 거예요. 이 작은 성공 경험이 앞으로 더 큰 시스템을 다루는 데 아주 소중한 밑거름이 될 것입니다.
- 도커 엔진과 컴포즈가 설치되어 있는지 먼저 확인하세요.
- docker-compose.yml 파일은 반드시 들여쓰기 규칙을 지켜야 해요.
- services 블록은 컨테이너의 핵심 설계도 역할을 해요.
- ports, image, volumes 옵션을 적절히 조합하여 서비스를 구성하세요.
- 실행은 docker compose up -d 명령어로 간편하게 할 수 있어요.
- 문제가 생기면 docker compose logs로 원인을 파악하세요.
오늘의 실습을 바탕으로 다음 단계로 나아가 보세요. 이번 주에는 데이터베이스(MySQL이나 PostgreSQL)를 서비스로 추가해 보고, 두 컨테이너를 서로 연결하는 방법을 연습해 보시는 것을 추천해요. 환경 변수를 통해 비밀번호를 넘겨주고, 볼륨을 통해 데이터를 보관하는 과정까지 익히면 여러분의 실력은 한 단계 더 도약할 거예요.
지금 바로 실습용 디렉터리를 만들고 첫 번째 컨테이너를 직접 띄워 보는 것은 어떨까요? 직접 눈으로 확인하는 순간, 진짜 배움이 시작됩니다.
더 깊이 있는 도커 활용법이 궁금하다면 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 참고해 보세요.
