갑자기 맡게 된 서버 운영, 이미지 옵션부터 막막하시죠?
어느 날 갑자기 선임자가 “이 서버 컴포즈 파일 좀 확인해 줘”라며 파일을 툭 던져주고 갔어요. 화면에는 알 수 없는 영어 단어들만 가득하고, 그중에서도 image라는 글자가 눈에 띄네요. 이걸 수정했다가 서버가 아예 멈춰버리면 어떡하지? 하는 걱정이 앞서기도 해요. 아마 지금 이 글을 읽고 계신 분도 비슷한 상황일 거예요.
개발자가 아닌 분들에게 도커(Docker)나 컴포즈(Compose)라는 용어는 마치 외계어처럼 느껴질 수 있어요. 특히 컨테이너를 실행할 때 가장 핵심이 되는 컴포즈 image 옵션 기초를 제대로 모르면, 내가 원하는 버전의 프로그램을 실행하지 못하거나 심지어 보안에 취약한 구버전을 올리는 큰 실수를 저지를 수도 있어요.
하지만 너무 걱정하지 마세요. 이미지 옵션은 사실 우리가 맛집에서 음식을 주문할 때 ‘메뉴 이름’과 ‘옵션’을 고르는 것과 아주 비슷하거든요. 이 원리만 이해하면 복잡한 설정 파일도 금방 읽어낼 수 있어요. 오늘 이 글을 끝까지 읽고 나면, 더 이상 검은 화면의 설정 파일을 보고 당황하지 않게 될 거예요.
이번 시간에는 다음과 같은 내용들을 차근차근 살펴볼게요.
- 이미지(Image)와 컨테이너(Container)의 근본적인 차이점
- 도커 컴포즈 파일에서 image 옵션을 작성하는 정확한 규칙
- 실무에서 바로 써먹을 수 있는 단계별 설정 예제
- 초보자가 가장 많이 하는 실수와 이를 해결하는 방법
컴포즈 파일에서 image 옵션은 어떤 프로그램을 가져와서 실행할지를 결정하는 가장 중요한 명령어예요. 이 값이 틀리면 서버는 시작조차 하지 못해요.
본격적인 시작 전, 꼭 알아야 할 핵심 용어 정리
컴포즈 파일을 열기 전에 먼저 용어라는 장벽을 넘어야 해요. 용어가 익숙해지면 텍스트가 눈에 들어오기 시작하거든요. 가장 많이 쓰이는 세 가지 개념만 먼저 머릿속에 넣어두세요.
1. 이미지(Image)와 컨테이너(Container)의 관계
가장 헷갈려 하시는 부분이에요. 쉽게 비유하자면 이미지는 요리 레시피이고, 컨테이너는 그 레시피대로 만들어진 실제 요리라고 생각하시면 돼요. 레시피(이미지)는 그대로 보관할 수 있지만, 실제로 먹으려면 요리(컨테이너)를 만들어야 하죠. 컴포즈 파일의 image 옵션은 바로 어떤 레시피를 쓸 것인지를 지정하는 거예요.
2. 레지스트리(Registry)와 도커 허브(Docker Hub)
레시피를 모아둔 거대한 도서관이 있다고 상상해 보세요. 이 도서관을 레지스트리라고 불러요. 그중에서 전 세계 사람들이 가장 많이 사용하는 공공 도서관이 바로 도커 허브예요. 우리가 컴포즈 파일에 이미지 이름을 적으면, 컴퓨터는 자동으로 이 도서관을 뒤져서 해당 이미지를 찾아와요.
3. 태그(Tag)와 버전 관리
레시피에 ‘떡볶이’라고만 적으면 매번 맛이 다를 수 있겠죠? 그래서 ‘매운 떡볶이 버전 2.0’처럼 구체적으로 적어줘야 해요. 여기서 ‘버전 2.0’에 해당하는 것이 바로 태그예요. 태그를 생략하면 기본적으로 latest(최신 버전)를 가져오게 되는데, 이게 나중에 큰 문제를 일으키기도 해요.
이미지 출처에 따른 선택 기준
어떤 이미지를 가져다 쓸지는 서버의 안정성과 직결되는 문제예요. 아래 표를 통해 어떤 기준으로 이미지를 선택해야 하는지 확인해 보세요.
| 이미지 유형 | 특징 | 추천 상황 |
|---|---|---|
| 공식 이미지 (Official) | 도커에서 검증한 가장 안전한 이미지 | 운영 서버, 중요 서비스 |
| 커뮤니티 이미지 | 개인이 만든 다양한 이미지 | 학습용, 개인 프로젝트 |
| 자체 빌드 이미지 | 회사 내부에서 직접 만든 이미지 | 사내 보안 프로그램 포함 시 |
검증되지 않은 개인의 이미지를 아무 데나 사용하면 보안에 구멍이 생길 수 있어요. 가급적 ‘Official’ 마크가 붙은 이미지를 우선적으로 고려하세요.
실전! 컴포즈 image 옵션으로 컨테이너 실행하기
이제 용어를 익혔으니 실제로 파일을 어떻게 작성하는지 알아볼 차례예요. 컴포즈 파일(docker-compose.yml)은 문법이 아주 엄격해서, 띄어쓰기 하나만 틀려도 바로 에러가 나요. 하지만 원리만 알면 아주 단순해요.
STEP 1. image 옵션의 기본 구조 이해하기
가장 기본적인 형태는 다음과 같아요. image: [이미지이름]:[태그]
예를 들어, 웹 서버로 유명한 Nginx를 사용하고 싶다면 image: nginx:1.21이라고 적어주면 돼요. 여기서 앞부분은 이름이고, 콜론(:) 뒤는 버전(태그)이에요.
STEP 2. 버전(Tag)을 명시해야 하는 결정적인 이유
많은 초보자가 실수하는 것 중 하나가 태그를 아예 안 쓰는 거예요. image: nginx라고만 적으면, 컴퓨터는 자동으로 nginx:latest를 찾아와요.
문제는 ‘최신(latest)’이라는 것이 언제든 변한다는 점이에요. 오늘까지 잘 돌아가던 서버가 내일 갑자기 멈췄다면, 그건 Nginx의 최신 버전이 업데이트되면서 기존 설정과 충돌이 일어났을 가능성이 높아요. 그래서 운영 서버에서는 반드시 특정 숫자로 된 버전(예: 1.21.1)을 명시하는 습관을 가져야 해요.
STEP 3. 직접 작성해 보는 docker-compose.yml 예제
자, 이제 실제 상황을 가정해 볼게요. 여러분이 웹 사이트를 운영하기 위해 웹 서버(Nginx)와 데이터베이스(MariaDB)가 동시에 필요한 상황이에요. 아래 내용을 그대로 따라 써보며 구조를 익혀보세요.
YAML 파일은 들여쓰기(Space)가 매우 중요해요. 탭(Tab) 키 대신 스페이스바를 사용하는 것을 권장합니다.
services:
web-server:
image: nginx:1.21-alpine
ports:
- "80:80"
database:
image: mariadb:10.6
environment:
MYSQL_ROOT_PASSWORD: password123위 코드에서 image 옵션을 잘 보세요. 웹 서버는 1.21 버전의 가벼운(alpine) 버전을 썼고, 데이터베이스는 10.6 버전을 썼어요. 이렇게 각각의 서비스에 맞는 이미지를 지정해 주는 것이 핵심이에요.
STEP 4. 명령어 실행과 이미지 다운로드 과정
파일을 다 작성했다면 터미널(검은 화면)을 열고 해당 폴더로 이동한 뒤, 다음 명령어를 입력하세요.
docker-compose up -d
이 명령어를 입력하면 컴퓨터는 다음과 같은 일을 순차적으로 수행해요.
- 작성된 파일을 읽고 어떤 이미지가 필요한지 파악해요.
- 도커 허브(도서관)에 해당 이미지가 있는지 확인해요.
- 없다면 인터넷에서 이미지를 다운로드(Pull)해요.
- 다운로드가 끝나면 이미지를 바탕으로 컨테이너(실제 서비스)를 실행해요.
실행 중에 화면에 Pulling이라는 글자가 지나간다면, 지금 열심히 이미지를 내려받고 있다는 뜻이니 차분히 기다려주시면 돼요.
STEP 5. 실행 확인 및 버전 체크하기
서버가 잘 돌아가는지 확인하려면 다음 명령어를 사용해 보세요. docker ps를 입력하면 현재 실행 중인 컨테이너 목록이 나와요. 이때 IMAGE 항목을 확인해서 내가 지정한 버전(예: nginx:1.21-alpine)이 정확히 떠 있는지 확인하는 것이 마지막 검수 단계예요.
- 새로운 서버를 세팅할 때는 항상 ‘버전이 명시된 이미지’를 사용하세요.
- 이미지 이름 뒤에 ‘:latest’가 붙어 있다면 즉시 특정 버전으로 수정하세요.
- 이미지가 너무 크다면 이름 뒤에 ‘-alpine’이 붙은 가벼운 버전을 찾아보세요.
자주 하는 실수와 해결법
서버를 처음 만지는 분들이라면 반드시 겪게 되는 문제들이 있어요. 당황해서 컴퓨터를 끄기 전에 아래 체크리스트를 먼저 확인해 보세요.
- ❌ 이미지 이름을 잘못 적었을 때
왜 발생하는가: 오타가 났거나 존재하지 않는 이미지를 요청했기 때문이에요.
✅ 해결법: 도커 허브 사이트에서 정확한 이미지 이름을 검색하고 복사해서 붙여넣으세요. - ❌ 태그(버전)를 생략했을 때
왜 발생하는가: ‘latest’를 가져오게 되어 예상치 못한 업데이트가 발생해요.
✅ 해결법: 반드시image: nginx:1.21처럼 숫자가 포함된 태그를 적어주세요. - ❌ 들여쓰기가 어긋났을 때
왜 발생하는가: YAML 파일은 띄어쓰기 개수에 따라 구조가 결정되기 때문이에요.
✅ 해결법: 모든 계층의 스페이스(공백) 개수가 일정한지 눈으로 확인하거나 에디터의 가이드를 활용하세요. - ❌ 이미지 아키텍처가 맞지 않을 때
왜 발생하는가: 내 컴퓨터(예: Mac M1/M2)와 서버의 CPU 방식이 다를 수 있어요.
✅ 해결법: 이미지 이름 뒤에 –platform linux/amd64 같은 옵션을 고려하거나 호환되는 이미지를 찾아야 해요. - ❌ 사내 전용 이미지를 못 가져올 때
왜 발생하는가: 로그인 정보가 없어서 허가된 도서관에 접근하지 못하는 상황이에요.
✅ 해결법:docker login명령어로 미리 인증을 마쳐야 해요.
자주 묻는 질문
Q. build 옵션과 image 옵션은 뭐가 다른가요?
image 옵션은 이미 만들어져 있는 레시피를 가져다 쓰는 것이고, build 옵션은 내가 직접 재료를 준비해서 레시피를 처음부터 만드는 과정이에요. 보통 이미 만들어진 것을 쓸 때는 image를 사용합니다.
Q. 이미지를 업데이트하려면 어떻게 해야 하나요?
컴포즈 파일에서 image의 태그(버전 숫자)를 바꾼 뒤, docker-compose up -d를 다시 실행하면 됩니다. 그러면 컴포즈가 알아서 새 버전을 다운로드하고 교체해 줘요.
Q. 왜 이미지를 다운로드하는 데 시간이 너무 오래 걸리나요?
이미지 용량이 크거나 네트워크 상태가 불안정할 때 그래요. 이럴 때는 이름 뒤에 alpine이 붙은 가벼운 버전을 사용하면 다운로드 시간을 획기적으로 줄일 수 있어요.
Q. 로컬에 있는 이미지를 사용할 수도 있나요?
네, 가능해요. 만약 내가 직접 만든 이미지를 컴퓨터에 저장해 두었다면, 태그를 명확히 지정했을 때 컴포즈가 인터넷이 아닌 내 컴퓨터에서 먼저 찾아보게 됩니다.
Q. 잘못된 이미지를 실행해서 서버가 멈췄어요. 어떻게 복구하나요?
가장 빠른 방법은 컴포즈 파일을 이전의 정상적이었던 버전으로 되돌린 뒤 다시 docker-compose up -d를 실행하는 거예요.
성공적인 컨테이너 운영을 위한 마무리
처음에는 낯선 영어 단어와 복잡한 코드 때문에 겁이 날 수 있지만, 컴포즈 image 옵션 기초를 하나씩 정복하다 보면 어느새 서버 환경을 자유자재로 다루는 자신을 발견하게 될 거예요. 오늘 배운 내용을 잊지 않도록 아래 요약 내용을 꼭 기억해 두세요.
- 이미지는 프로그램의 레시피, 컨테이너는 실제 프로그램이다.
- 운영 서버에서는 ‘latest’ 태그 대신 반드시 ‘특정 버전’을 명시하자.
- 이미지 이름과 태그 사이에는 콜론(:)을 사용한다.
- YAML 파일은 들여쓰기에 매우 민감하므로 주의하자.
- 용량이 부담된다면 ‘-alpine’ 버전의 이미지를 고려하자.
오늘의 학습을 마쳤다면, 바로 실습해 보는 건 어떨까요? 지금 당장 메모장을 열어 간단한 Nginx 설정 파일을 작성해 보세요. 이론으로만 보는 것과 직접 명령어를 쳐보는 것은 하늘과 땅 차이니까요. 이해가 안 되는 용어는 그냥 넘기지 말고, 예제로 한 번씩 실행해 보며 감을 익히는 것이 가장 빠른 길이에요.
다음에 배울 내용은 컨테이너를 더 안전하게 보호하고 데이터를 영구적으로 저장하는 방법이에요. 서버 운영의 다음 단계로 나아갈 준비가 되셨나요? 함께 천천히 나아가 봅시다.
도커 컴포즈의 더 깊은 활용법이 궁금하다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 참고해 보세요.
