[IT-방법] 컴포즈 image 옵션 시작하기 – 이미지 설정부터 컨테이너 실행까지 초보자용 가이드

도입 — 왜 지금 컴포즈 image 옵션인가

분명히 튜토리얼을 그대로 따라 했는데, 터미널에 빨간색 에러 메시지가 가득 차면 정말 당황스럽죠? 특히 컨테이너를 처음 다루는 주니어 개발자라면 컴포즈 image 옵션 시작하기 단계에서 발목을 잡히는 경우가 정말 많아요. “도대체 이미지가 어디에 있다는 거지?” 혹은 “왜 내가 설정한 이미지가 작동하지 않는 걸까?” 하는 고민은 누구나 한 번쯤 겪는 과정이에요.

최근 데브옵스(DevOps) 환경이 고도화되면서, 단순히 명령어를 입력하는 것을 넘어 컨테이너의 설계도라고 할 수 있는 이미지를 어떻게 관리하고 연결하는지가 실무 역량의 핵심이 되었어요. 도커 컴포즈(Docker Compose)는 여러 개의 컨테이너를 효율적으로 관리하게 도와주지만, 그 기초 중의 기초는 바로 어떤 이미지를 가져와서 어떤 컨테이너를 만들 것인지 명시하는 image 옵션 설정에 달려 있어요.

이 설정을 제대로 이해하지 못하면, 매번 수동으로 이미지를 내려받아야 하거나 잘못된 버전의 소프트웨어를 실행하여 서비스 전체를 망가뜨릴 수도 있어요. 그래서 오늘 이 글에서는 여러분이 시행착오를 겪지 않도록, 가장 기초적인 설치부터 실제 서비스가 돌아가는 첫 실행까지를 30분이라는 짧은 시간 안에 마스터할 수 있도록 도와드릴게요.

이 글을 끝까지 읽고 나면 다음과 같은 것들을 확실히 얻어갈 수 있어요.

• 도커 컴포즈를 실행하기 위한 최소한의 환경 구축 방법
• docker-compose.yml 파일에서 image 옵션을 정확하게 작성하는 문법
• 설정한 이미지가 정상적으로 컨테이너로 구동되는지 확인하는 실무 절차
• 실행 중 발생하는 흔한 오류들을 스스로 해결하는 문제 해결 능력

사전 준비 — 기본 이해와 체크리스트

본격적인 실습에 들어가기 전에, 우리가 어떤 도구를 사용하고 무엇을 준비해야 하는지 명확히 짚고 넘어가야 해요. 무작정 명령어부터 입력하다 보면 환경 설정의 작은 차이 때문에 예상치 못한 오류를 만나게 되거든요. 컴포즈 image 옵션 시작하기를 위해서는 가장 먼저 도커 엔진(Docker Engine)이 여러분의 컴퓨터에서 숨 쉬듯 잘 작동하고 있어야 해요.

필수 준비물 및 환경 점검

우선 여러분의 운영체제에 맞는 도커 설치 환경을 확인해 주세요. 윈도우(Windows) 사용자라면 Docker Desktop을 설치하는 것이 가장 간편하고, 맥(macOS) 사용자 역시 동일한 방식을 추천해요. 리눅스(Linux) 환경이라면 도커 엔진과 도커 컴포즈 플러그인을 별도로 설치해야 할 수도 있으니 주의가 필요해요. 아래 표를 통해 여러분이 현재 어떤 상황인지, 어떤 준비가 필요한지 비교해 보세요.

또한, 우리가 다룰 도커 컴포즈는 여러 개의 이미지를 조합하여 하나의 완성된 서비스를 만드는 조율사 역할을 해요. 따라서 이미지 하나를 다루는 법을 아는 것은, 나중에 데이터베이스와 웹 서버를 동시에 띄우는 복잡한 시스템을 구축하기 위한 첫걸음이 될 거예요.

주의하세요! 이미지를 가져올 때는 반드시 인터넷 연결이 되어 있어야 하며, 도커 허브(Docker Hub)와 같은 공용 저장소에 해당 이미지가 존재하는지 미리 확인하는 습관을 들여야 해요. 존재하지 않는 이미지 이름을 적는 것만큼 허무한 실수는 없으니까요.

핵심 본문 — 단계별 실행 가이드

이제 준비는 끝났어요. 실제로 손을 움직여서 컨테이너를 띄워볼 시간이에요. 우리는 가장 대중적이고 가벼운 웹 서버인 Nginx(엔진엑스)를 사용하여 실제 웹 페이지가 뜨는 것을 확인해 볼 거예요. 이 과정을 통해 컴포즈 image 옵션이 어떻게 작동하는지 몸소 체험할 수 있어요.

STEP 1. 실습용 작업 디렉터리 생성하기

가장 먼저 프로젝트를 진행할 깨끗한 공간을 만들어야 해요. 바탕화면이나 문서 폴더 어디든 상관없지만, 나중에 관리하기 편하도록 별도의 폴더를 만드는 것을 추천해요. 터미널(Terminal) 또는 명령 프롬프트(CMD)를 열고 아래와 같이 입력해 보세요.

1. 작업할 폴더를 만듭니다: mkdir my-web-server
2. 생성한 폴더로 이동합니다: cd my-web-server

이렇게 하면 여러분만의 작은 실험실이 만들어진 거예요. 이 폴더 안에서 모든 설정 파일과 컨테이너 데이터가 관리될 예정이에요.

STEP 2. 최소 설정 파일(docker-compose.yml) 작성하기

이제 핵심인 설정 파일을 만들 차례예요. 메모장이나 VS Code 같은 에디터를 열고, 폴더 안에 docker-compose.yml이라는 이름의 파일을 생성하세요. 파일 이름에 오타가 있으면 도커가 파일을 찾지 못하니 주의해야 해요. 파일 안에는 아래의 내용을 그대로 입력해 주세요.

version: '3.8'
services:
  my-web:
    image: nginx:latest
    ports:
      - "8080:80"

방금 작성한 코드의 의미를 하나씩 뜯어볼까요?
1. version: 컴포즈 파일의 형식을 지정해요.
2. services: 우리가 실행할 컨테이너들의 목록을 정의하는 영역이에요.
3. image: 바로 오늘 우리가 배우는 핵심 옵션이에요! nginx:latest라고 적음으로써, 도커에게 “가장 최신 버전의 Nginx 이미지를 가져와서 사용해 줘”라고 명령하는 것이죠.
4. ports: 내 컴퓨터의 8080번 포트와 컨테이너 내부의 80번 포트를 연결해 줘서, 웹 브라우저로 접속할 수 있게 길을 만들어주는 거예요.

STEP 3. 컨테이너 실행과 동작 확인

설정 파일 작성을 마쳤다면 이제 마법을 부릴 시간이에요. 다시 터미널로 돌아가서 방금 만든 폴더 위치에 있는지 확인한 후, 아래 명령어를 입력하세요.

docker compose up -d

이 명령어를 입력하면 도커는 다음과 같은 순서로 행동해요.
첫째, docker-compose.yml 파일을 읽어요.
둘째, 지정된 nginx:latest 이미지가 내 컴퓨터에 있는지 확인해요.
셋째, 이미지가 없다면 도커 허브에서 자동으로 다운로드(Pull)를 시작해요.
넷째, 다운로드가 완료되면 이미지를 바탕으로 컨테이너를 생성하고 실행해요.
다섯째, -d 옵션 덕분에 백그라운드에서 조용히 돌아가게 돼요.

실행이 완료되었다면, 웹 브라우저(Chrome이나 Edge 등)를 열고 주소창에 localhost:8080을 입력해 보세요. 화면에 “Welcome to nginx!”라는 문구가 보인다면, 여러분은 방금 첫 번째 컨테이너 운영에 성공한 거예요! 정말 축하드려요!

STEP 4. 실행 중인 컨테이너 상태 점검하기

성공적으로 떴다고 해서 끝이 아니에요. 실무에서는 컨테이너가 정말 의도한 대로 잘 돌아가고 있는지 확인하는 과정이 매우 중요해요. 아래 명령어들을 활용해 보세요.

• docker compose ps: 현재 실행 중인 서비스의 목록과 상태, 포트 정보를 한눈에 보여줘요.
• docker compose logs -f: 컨테이너 내부에서 어떤 일이 일어나고 있는지 실시간으로 로그를 보여줘요. 에러가 발생했을 때 가장 먼저 확인해야 할 도구예요.

STEP 5. 정리와 재실행 연습

실습을 마무리하기 위해 컨테이너를 정지시켜 봅시다. docker compose stop을 입력하면 실행 중인 컨테이너가 멈춰요. 완전히 삭제하고 싶다면 docker compose down을 사용하세요. 주의하세요! down 명령어를 쓰면 컨테이너뿐만 아니라 생성했던 네트워크 정보도 모두 삭제되니, 나중에 다시 띄울 때 설정 파일을 다시 읽어야 한다는 점을 기억하세요.

이제 여러분은 이미지를 지정하고, 파일을 만들고, 실행하고, 확인하는 전체 흐름을 이해했어요. 이 과정은 앞으로 여러분이 다룰 수백 가지의 다양한 기술 스택에도 똑같이 적용되는 아주 소중한 경험이 될 거예요.

자주 하는 실수와 해결법

실습을 하다 보면 반드시 마주하게 되는 벽들이 있어요. 당황하지 말고 아래 리스트를 보며 어떤 상황인지 체크해 보세요.

• ❌ 이미지를 찾을 수 없다는 에러 (Image not found)
  왜 발생하는가: docker-compose.yml 파일의 이미지 이름에 오타가 있거나, 도커 허브에 존재하지 않는 이름을 적었을 때 발생해요.
  ✅ 해결법: 이미지 이름과 태그(예: :latest)가 정확한지 다시 확인하고, 도커 허브 웹사이트에서 검색해 보세요.
• ❌ 포트 충돌 에러 (Bind for 0.0.0.0:8080 failed)
  왜 발생하는가: 이미 내 컴퓨터의 8080번 포트를 다른 프로그램(예: 다른 웹 서버나 개발 툴)이 사용하고 있기 때문이에요.
  ✅ 해결법: ports 설정에서 앞쪽 숫자를 8081:80이나 9000:80처럼 다른 번호로 바꿔주세요.
• ❌ 권한 거부 에러 (Permission denied)
  왜 발생하는가: 리눅스 환경에서 도커 명령어를 실행할 권한이 부족할 때 나타나요.
  ✅ 해결법: 명령어 앞에 sudo를 붙여 실행하거나, 사용자를 docker 그룹에 추가해야 해요.
• ❌ 파일 형식 오류 (YAML syntax error)
  왜 발생하는가: YAML 파일은 들여쓰기(Space)에 매우 민약해요. 탭(Tab)을 섞어 쓰거나 칸 수가 맞지 않으면 에러가 나요.
  ✅ 해결법: 반드시 스페이스(Space)를 사용하여 일정한 간격으로 들여쓰기를 맞추세요.
• ❌ 이미지 업데이트가 안 됨
  왜 발생하는가: 이미 내 컴퓨터에 같은 이름의 이미지가 있어서 새로운 것을 받아오지 않는 경우예요.
  ✅ 해결법: docker compose pull 명령어를 사용하여 이미지를 강제로 새로 내려받으세요.

자주 묻는 질문

Q. 이미지를 매번 새로 다운로드받아야 하나요?

아니요, 한 번 내려받은 이미지는 내 컴퓨터의 로컬 저장소에 저장되어 있어요. 다음에 같은 이미지를 사용할 때는 다운로드 과정 없이 즉시 실행되니 안심하세요.

Q. image 옵션 대신 build 옵션을 쓰는 건 무엇이 다른가요?
image는 이미 만들어진 완성품을 가져오는 것이고, build는 내가 직접 재료(Dockerfile)를 준비해서 요리(이미지 생성)를 하는 과정이에요.

Q. 특정 버전을 지정하는 것이 왜 중요한가요?
실무 환경에서는 서비스의 안정성이 최우선이에요. 최신 버전이 무조건 좋은 게 아니라, 기존에 잘 돌아가던 버전과 동일한 환경을 유지해야 예상치 못한 오류를 방지할 수 있기 때문이에요.

Q. 도커 컴포즈 실행 중에 컴퓨터가 너무 느려졌어요.
컨테이너가 너무 많은 메모리나 CPU를 점유하고 있을 수 있어요. docker stats 명령어로 어떤 컨테이너가 자원을 많이 쓰는지 확인해 보세요.

핵심 요약과 다음 단계

오늘 우리는 컴포즈를 이용해 이미지를 다루고 컨테이너를 띄우는 아주 중요한 첫 단계를 마쳤어요. 처음이라 낯설 수 있지만, 이 기본기가 탄탄해야 나중에 복잡한 마이크로서비스 아키텍처(MSA)도 거뜬히 다룰 수 있게 된답니다.

오늘 배운 내용을 바탕으로, 다음에는 무엇을 하면 좋을까요? 여러분의 성장 단계에 맞춰 제안해 드릴게요.

• 오늘 할 일: 방금 만든 Nginx 컨테이너를 docker compose down으로 끄고 다시 켜 보세요.
• 이번 주 할 일: Nginx 대신 mysql이나 redis 같은 데이터베이스 이미지를 사용해서 설정 파일을 만들어 보세요.
• 실행 직전 할 일: 이미지를 직접 빌드하는 방법인 build 옵션과 Dockerfile의 관계를 공부해 보세요.

지금 바로 실습용 디렉터리를 만들고 첫 컨테이너를 띄워 보는 것은 어떨까요? 직접 명령어를 입력하고 웹 페이지가 뜨는 순간의 쾌감은 무엇과도 바꿀 수 없는 학습 동기가 될 거예요!

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