[IT-방법] 컴포즈 image 옵션 설정 예제 및 활용 가이드 – docker-compose.yml 이미지 관리의 모든 것

도커 컴포즈 이미지 설정이 꼬일 때 시작하는 법

서버를 처음 올릴 때 가장 당혹스러운 순간이 언제인가요? 아마도 분명히 예제대로 작성했는데 “image not found”라는 빨간색 에러 메시지를 마주할 때일 거예요. 혹은 분명히 어제까지 잘 돌아가던 컨테이너가 오늘 갑자기 작동하지 않아 당황하며 로그를 뒤지는 상황도 자주 발생하죠.

이런 문제는 대부분 docker-compose.yml 파일 안의 image 옵션을 제대로 다루지 못해서 생겨요. 어떤 이미지를 가져올지, 어떤 버전을 사용할지, 그리고 우리가 직접 만든 이미지를 어떻게 불러올지에 대한 기준이 명확하지 않으면 컨테이너 운영은 매번 도박처럼 느껴질 수밖에 없어요.

단순히 이미지를 적는 것을 넘어, 실무에서는 보안을 위해 사설 저장소를 사용하거나 배포의 안정성을 위해 특정 태그를 고정해야 하는 등 고려할 점이 정말 많아요. 이 글은 설정 파일 작성이 아직 서툰 개발자나, 매번 이미지 버전 문제로 골머리를 앓는 운영자를 위해 준비했어요.

글을 다 읽고 나면 여러분은 다음과 같은 능력을 갖추게 돼요.

• 상황별로 가장 적합한 컴포즈 image 옵션 설정 예제를 바로 적용할 수 있어요.
• 단순한 이미지 호출을 넘어 사설 레지스트리와 빌드 옵션을 조합하는 법을 익혀요.
• 이미지 버전 충돌이나 권한 문제 같은 흔한 에러를 스스로 해결할 수 있어요.
• 안정적인 컨테이너 운영을 위한 이미지 관리 전략을 세울 수 있어요.

이미지 설정을 시작하기 전 반드시 알아야 할 기초

컴포즈 파일에서 이미지를 지정하기 전에, 우리가 다루려는 대상이 무엇인지 명확히 구분해야 해요. 도커 이미지는 단순히 실행 파일의 묶음이 아니라, 특정 환경이 통째로 박제된 상태라고 이해하면 훨씬 쉬워요. 이 상태를 어떻게 호출하느냐에 따라 서버의 운명이 결정돼요.

본격적으로 코드를 짜기 전에, 여러분이 사용하려는 이미지의 출처가 어디인지 먼저 판단해야 해요. 출처에 따라 작성해야 하는 YAML 형식이 완전히 달라지거든요. 아래 표를 보고 지금 여러분의 상황이 어디에 해당하는지 먼저 체크해 보세요.

이미지를 선택할 때 가장 주의해야 할 점은 “버전 관리”예요. 많은 초보자가 귀찮다는 이유로 이미지 이름 뒤에 태그를 붙이지 않아요. 이렇게 되면 도커는 자동으로 latest라는 태그를 찾게 되는데, 이게 정말 위험해요. 며칠 뒤에 이미지의 내용이 업데이트되면서 기존에 잘 돌아가던 코드가 갑자기 에러를 뿜어낼 수 있기 때문이에요.

준비가 끝났다면 이제 실제 컴포즈 파일에 어떻게 적어야 하는지, 단계별로 실전 예제를 살펴볼게요.

상황별 컴포즈 image 옵션 실전 예제

이제 본격적으로 컴포즈 image 옵션 설정 예제를 하나씩 뜯어볼게요. 단순히 코드를 복사하는 것이 아니라, 왜 이렇게 써야 하는지 그 이유를 이해하는 것이 핵심이에요.

STEP 1. 가장 기초적인 공식 이미지 호출하기

가장 먼저 해볼 일은 누구나 아는 공식 이미지를 불러오는 거예요. 웹 서버로 가장 많이 쓰이는 Nginx를 예로 들어볼게요. 가장 단순한 형태는 이미지 이름과 태그를 조합하는 방식이에요.

services:
  web-server:
    image: nginx:1.25.3
    ports:
      - "80:80"

여기서 중요한 점은 nginx:1.25.3처럼 버전을 명확히 적었다는 거예요. 만약 그냥 nginx라고만 적으면, 나중에 Nginx가 1.26 버전으로 업데이트되었을 때 내 서버도 의도치 않게 업데이트되어 버려요. 이런 불확실성을 없애는 것이 운영의 첫걸음이에요.

STEP 2. 사설 레지스트리(Private Registry) 사용하기

회사 업무를 하다 보면 도커 허브가 아닌, 회사 내부적으로 운영하는 사설 레지스트리에서 이미지를 가져와야 할 때가 많아요. 이때는 이미지 이름 앞에 레지스트리의 주소를 반드시 붙여줘야 해요.

services:
  my-app:
    image: registry.mycompany.com/project-a/api-server:v2.1.0
    restart: always

위 예제에서 registry.mycompany.com은 이미지가 저장된 서버 주소예요. 이렇게 경로를 길게 적어주지 않으면 도커는 무조건 외부 도커 허브에서 이미지를 찾으려다 “Access Denied” 에러를 내뱉게 돼요. 사설 저장소를 사용할 때는 미리 docker login 명령어로 인증을 마친 상태여야 한다는 점도 잊지 마세요.

STEP 3. 이미지 빌드와 이름 지정 동시 수행하기

이미 만들어진 이미지를 가져오는 게 아니라, 내가 가진 Dockerfile을 직접 빌드해서 사용하고 싶을 때가 있죠? 이때는 build 옵션과 image 옵션을 함께 사용하면 아주 유용해요.

services:
  backend-api:
    build: ./backend
    image: my-local-app:latest
    ports:
      - "8080:8080"

이 설정의 마법은 build가 실행된 결과물에 image: my-local-app:latest라는 이름을 붙여준다는 데 있어요. 이렇게 하면 빌드된 이미지를 나중에 다른 곳에서 다시 쓰거나, 관리하기가 훨씬 수월해져요. 그냥 빌드만 하면 도커가 무작위 이름을 붙여버려서 나중에 찾기 힘들거든요.

STEP 4. 환경 변수를 활용한 유연한 이미지 관리

개발 환경, 테스트 환경, 실제 운영 환경마다 사용하는 이미지 버전이 다를 수 있어요. 매번 파일을 수정하는 건 너무 번거롭죠. 이때는 환경 변수를 활용해 보세요.

services:
  database:
    image: postgres:${DB_VERSION:-15-alpine}
    environment:
      POSTGRES_PASSWORD: password

위 코드를 보면 ${DB_VERSION:-15-alpine} 부분이 보이실 거예요. 이는 .env 파일에 DB_VERSION 값이 있으면 그 값을 쓰고, 없으면 기본값으로 15-alpine을 사용하라는 뜻이에요. 이렇게 하면 하나의 파일로 여러 환경에 대응할 수 있어 아주 효율적이에요.

STEP 5. 실무형 멀티 서비스 구성 시나리오

마지막으로, 웹 서버와 데이터베이스를 동시에 띄우는 실제 서비스 시나리오를 만들어 볼게요. 각 서비스의 목적에 맞는 이미지 설정 방식을 한눈에 확인할 수 있어요.

services:
  # 1. 공식 이미지를 사용하여 DB 구성
  db:
    image: mariadb:10.6
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: secret_password

  # 2. 직접 빌드한 이미지를 사용하여 API 서버 구성
  api:
    build: ./api-service
    image: my-company/api-prod:1.0.4
    depends_on:
      - db

  # 3. 사설 저장소의 이미지를 사용하여 캐시 서버 구성
  cache:
    image: internal-reg.local/redis:7.0-alpine

volumes:
  db_data:

이 시나리오처럼 각 서비스의 성격에 맞춰 이미지를 가져오는 방식이 달라져야 해요. 데이터베이스처럼 검증이 중요한 건 공식 이미지의 특정 버전을 쓰고, 내가 만든 코드는 직접 빌드하며, 내부 공통 모듈은 사설 레지스트리를 이용하는 방식이죠. 이것이 바로 숙련된 개발자가 컨테이너를 구성하는 방식이에요.

자주 하는 실수와 해결법

실무에서 이미지 설정과 관련하여 가장 빈번하게 발생하는 문제들을 정리했어요. 에러 메시지가 떴을 때 당황하지 말고 이 리스트를 확인해 보세요.

• ❌ “manifest for image not found” → 이미지 이름이나 태그에 오타가 있거나, 해당 태그가 실제로 존재하지 않는 경우예요.
  ✅ 도커 허브 웹사이트에서 해당 이미지의 태그가 존재하는지 다시 한번 확인해 보세요.
• ❌ “pull access denied for…” → 사설 저장소에 접근할 권한이 없다는 뜻이에요.
  ✅ docker login [레지스트리주소] 명령어로 로그인이 되어 있는지 확인하세요.
• ❌ “no matching manifest for linux/arm64/v8” → Apple Silicon(M1/M2) 맥북을 쓰는데, 이미지가 인텔(x86_64)용으로만 만들어진 경우예요.
  ✅ 이미지 이름 뒤에 :alpine처럼 가벼운 버전을 찾거나, --platform linux/amd64 옵션을 고려해 보세요.
• ❌ 이미지가 업데이트되었는데 반영이 안 돼요 → 도커는 이미 로컬에 같은 이름의 이미지가 있으면 새로 받지 않아요.
  ✅ docker-compose pull 명령어를 먼저 실행해서 새 이미지를 내려받은 뒤 다시 시작하세요.
• ❌ YAML 문법 에러 → 들여쓰기가 한 칸이라도 틀리면 에러가 나요.
  ✅ docker-compose config 명령어를 입력해 문법이 맞는지 미리 검증하세요.

자주 묻는 질문

Q. 왜 latest 태그를 쓰면 안 된다는 건가요?

latest는 말 그대로 ‘가장 최신’이라는 뜻인데, 이 최신이 언제 바뀔지 아무도 몰라요. 오늘 잘 돌아가던 서버가 내일 자동으로 업데이트되면서 갑자기 멈출 수 있기 때문에, 반드시 특정 버전을 고정하는 것이 안전해요.

Q. image와 build 옵션을 같이 써도 되나요?

네, 아주 좋은 방법이에요! build는 이미지를 만드는 과정을 담당하고, image는 만들어진 이미지에 이름을 붙여주는 역할을 해요. 이렇게 하면 빌드된 이미지를 관리하기가 훨씬 편해져요.

Q. .env 파일에 적은 변수가 안 먹히는 것 같아요.

docker-compose.yml 파일과 같은 폴더에 .env 파일이 있는지 확인해 보세요. 파일 이름이 정확히 .env여야 하며, 변수명 앞뒤에 공백이 없는지도 체크해야 해요.

Q. 사설 레지스트리 주소를 안 적으면 어떻게 되나요?

도커는 기본적으로 모든 이미지를 도커 허브(Docker Hub)에서 찾으려고 해요. 사설 저장소의 주소를 적지 않으면 당연히 이미지를 찾지 못하고 에러를 내뱉게 돼요.

안정적인 컨테이너 운영을 위한 마무리

도커 컴포즈의 image 옵션은 단순히 이름을 적는 칸이 아니라, 여러분의 서비스가 얼마나 안정적으로 돌아갈지를 결정하는 중요한 설계도예요. 오늘 배운 내용을 바탕으로 설정 파일을 다시 한번 점검해 보세요.

이제 이론은 충분해요. 지금 바로 여러분의 프로젝트 폴더로 가서 docker-compose.yml 파일을 열어보세요. 혹시 모든 이미지가 latest로 되어 있지는 않나요? 그렇다면 오늘 바로 적절한 버전 태그로 교체하는 작업을 시작해 보세요. 그 작은 변화가 미래의 장애를 막아줄 거예요.

작성 중인 설정 파일이 잘 작동하는지 확신이 서지 않는다면, 제가 정리해둔 예제 파일을 내려받아 프로젝트 구조에 맞게 값만 바꿔서 테스트해 보세요. 훨씬 빠르게 감을 잡으실 수 있을 거예요.

다음 단계로 넘어가고 싶다면, 도커 컴포즈의 더 깊은 개념을 다룬 가이드를 읽어보는 것을 추천해요. 컨테이너 네트워크와 볼륨 설정까지 익히면 여러분은 진정한 데브옵스 역량을 갖추게 될 거예요.

도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드