[IT-정보] 컴포즈 services 기초 설정 가이드 – 초보자도 바로 쓰는 서비스 블록 구성법

갑자기 맡게 된 서버 관리, 서비스 블록부터 막히나요?

어느 날 갑자기 선임자로부터 “이제 서버 운영은 담당해 주세요”라는 말을 들었다면 정말 눈앞이 캄캄할 거예요. 특히 모니터를 가득 채운 검은 화면과 알 수 없는 영어 단어들이 가득한 docker-compose.yml 파일을 마주했을 때의 그 막막함은 경험해 본 사람만 알 수 있어요.

파일을 열어보니 가장 먼저 보이는 건 services:라는 문구예요. 이 밑에 적힌 수많은 설정값이 대체 무슨 뜻인지, 하나라도 잘못 적으면 서버가 통째로 멈추는 건 아닌지 걱정이 앞서기 마련이죠. 기존 개발자들에게는 숨 쉬듯 당연한 용어들이지만, 비전공자나 서버 운영 초보자에게는 외계어처럼 느껴지는 게 당연해요.

하지만 너무 걱정하지 마세요. 서비스 블록은 생각보다 아주 논리적이고 규칙적인 구조로 이루어져 있어요. 이 규칙만 이해하면 복잡해 보이던 설정값들도 마치 잘 짜인 레시피처럼 읽히기 시작할 거예요. 오늘 이 글을 끝까지 읽고 나면, 더 이상 서비스 블록 앞에서 머뭇거리지 않고 자신 있게 설정을 수정할 수 있게 돼요.

이 글에서는 다음과 같은 내용을 차근차근 다룰 예정이에요.

• 서비스 블록을 구성하는 핵심 용어의 쉬운 정의
• 설정값에 따라 컨테이너가 어떻게 변하는지 보여주는 비교표
• 실제 코드를 활용한 단계별 서비스 구성 방법
• 실무에서 가장 자주 겪는 설정 오류와 해결책

본격적인 시작 전, 꼭 알아야 할 기본 개념 정리

설정 파일을 만지기 전에 우리가 사용하는 언어부터 통일할 필요가 있어요. 도커 컴포즈(Docker Compose)라는 도구는 여러 개의 컨테이너를 하나의 묶음으로 관리해 주는 비서 같은 존재예요. 그리고 그 비서가 관리하는 개별 작업 단위가 바로 service예요.

서비스 블록을 작성할 때 가장 헷갈리는 세 가지 개념을 먼저 확실히 짚고 넘어갈게요. 이 차이를 모르면 나중에 “왜 제가 설정한 대로 작동하지 않죠?”라는 질문을 스스로 던지게 될 수도 있어요.

서비스 블록은 결국 “어떤 레시피(Image)를 사용해서, 어떤 환경(Environment)을 만들고, 어떤 문(Port)을 열어줄 것인가”를 적어두는 명세서라고 생각하면 쉬워요.

이제 준비는 끝났어요. 본격적으로 서비스 블록의 내부를 하나씩 파헤쳐 볼게요.

서비스 블록 완벽 정복: 단계별 설정 가이드

이제 실제 docker-compose.yml 파일의 속으로 들어가 볼 시간이에요. 서비스 블록 하나를 제대로 만들기 위해 거쳐야 하는 5단계를 차근차근 설명해 드릴게요.

STEP 1. 서비스의 이름과 이미지 결정하기

서비스 블록의 시작은 이름표를 붙이는 일이에요. services: 아래에 적는 첫 번째 이름은 여러분이 관리하기 편한 이름이면 돼요. 예를 들어 웹 서버라면 web:이라고 적으면 충분해요.

그다음 가장 중요한 것이 image 설정이에요. 이건 어떤 프로그램을 가져올지를 정하는 건데, 마치 앱스토어에서 앱을 다운로드받는 것과 비슷해요. image: nginx:latest라고 적으면 최신 버전의 Nginx 웹 서버를 가져오겠다는 뜻이 돼요. 여기서 주의할 점은 버전(Tag)을 명시하는 습관이에요. 단순히 latest라고만 적으면 나중에 업데이트될 때 예기치 못한 문제가 생길 수 있으니, 가급적 특정 숫자가 적힌 버전을 사용하는 게 안전해요.

STEP 2. 외부와 소통할 통로, 포트(Ports) 설정하기

이미지를 가져왔다고 해서 바로 웹사이트가 보이는 건 아니에요. 컴퓨터 내부의 특정 문을 열어서 외부 사람이 들어올 수 있게 해줘야 하는데, 이게 바로 ports 설정이에요. 포트 설정은 항상 호스트_포트:컨테이너_포트 형식을 따라요.

예를 들어 ports: - "8080:80"이라고 적었다면, 외부 사용자가 내 서버의 8080번 포트로 접속했을 때 컨테이너 내부의 80번 포트로 연결해 주겠다는 의미예요. 마치 아파트 호수(컨테이너 포트)로 가기 위해 단지 정문(호스트 포트)의 특정 게이트를 통과하는 것과 같아요.

STEP 3. 개인화된 설정값, 환경 변수(Environment) 넣기

프로그램을 실행할 때 비밀번호나 데이터베이스 주소처럼 매번 바뀌는 정보들이 있죠? 이걸 일일이 코드에 적으면 보안에도 안 좋고 수정도 힘들어요. 이럴 때 쓰는 것이 environment예요. 서비스 블록 안에 환경 변수를 정의해 두면, 프로그램이 실행될 때 그 값을 읽어서 동작하게 돼요. 예를 들어 데이터베이스의 관리자 비밀번호를 설정하는 식이죠. 이 과정은 마치 요리할 때 소금의 양을 조절하는 것과 같아서, 같은 요리법이라도 환경 변수에 따라 맛(동작)이 달라질 수 있어요.

STEP 4. 데이터 저장소, 볼륨(Volumes) 연결하기

컨테이너는 아주 깔끔한 성격이에요. 컨테이너가 꺼지거나 삭제되면 그 안에서 작업했던 데이터도 모두 사라져 버려요. 만약 웹 서버에 올린 사진이나 데이터베이스에 저장한 게시글이 사라진다면 정말 큰일이겠죠? 이를 방지하기 위해 volumes를 사용해요.

볼륨은 컨테이너 내부의 폴더와 실제 서버의 폴더를 연결해 주는 작업이에요. 이렇게 연결해 두면 컨테이너가 아무리 생겼다 사라져도, 실제 데이터는 서버의 하드디스크에 안전하게 남아있게 돼요. 마치 USB 메모리를 컴퓨터에 꽂아서 파일을 저장하는 것과 비슷한 원리라고 이해하면 쉬워요.

STEP 5. 서비스 간의 순서 정하기, 의존성(Depends_on) 관리

실제 서비스는 혼자 작동하지 않아요. 웹 서버는 반드시 데이터베이스가 먼저 켜져 있어야 제대로 작동할 수 있죠. 이때 사용하는 것이 depends_on이에요. 이 설정을 통해 “웹 서버를 켜기 전에 데이터베이스부터 먼저 실행해 줘”라고 순서를 정해줄 수 있어요. 순서가 꼬여서 데이터베이스가 준비되지 않았는데 웹 서버가 먼저 달려들면 에러가 발생하니까요.

자, 이제 배운 내용을 바탕으로 실제 예제를 살펴볼까요? 아래는 웹 서버와 데이터베이스를 연결하는 아주 간단한 구성표예요.

[실무 적용 예제: 웹 서버와 DB 연결하기]

이 시나리오는 사용자가 접속할 수 있는 웹 페이지와 데이터를 담아둘 데이터베이스를 동시에 띄우는 예시예요.

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: mysecretpassword
    volumes:
      - ./db_data:/var/lib/mysql

  web:
    image: nginx:latest
    ports:
      - "80:80"
    depends_on:
      - db

위 코드를 보면 db 서비스가 먼저 정의되어 있고, web 서비스는 depends_on: - db를 통해 DB가 먼저 켜지기를 기다려요. 또한 DB의 데이터는 ./db_data라는 현재 폴더의 디렉토리에 안전하게 저장되도록 설정되어 있죠.

이처럼 서비스 블록을 하나씩 쌓아 올리다 보면, 복잡해 보이던 전체 서버 구조가 머릿속에 그려지기 시작할 거예요.

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

설정 파일을 작성하다 보면 분명히 맞게 쓴 것 같은데 왜 안 되는지 답답할 때가 많죠? 초보자들이 가장 많이 겪는 5가지 실수를 정리했어요.

• ❌ YAML 들여쓰기 오류 → 줄 맞춤을 잘못해서 컴포즈가 파일을 읽지 못해요.
  ✅ 해결법: 반드시 스페이스(Space)를 사용하고, 메모장보다는 VS Code 같은 전문 에디터를 사용해 눈금선(Indent Guide)을 확인하세요.
• ❌ 포트 충돌 → 이미 다른 프로그램이 사용 중인 포트를 쓰려고 할 때 발생해요.
  ✅ 해결법: ports: - "8080:80"처럼 호스트 포트를 바꿔가며 사용 가능한 번호를 찾으세요.
• ❌ 볼륨 경로 오류 → 데이터가 저장될 폴더 경로를 잘못 적으면 에러가 나요.
  ✅ 해결법: 상대 경로(./)와 절대 경로(/)를 명확히 구분해서 적어주세요.
• ❌ 환경 변수 오타 → MYSQL_PASSWORD를 MYSQL_PWD라고 적는 경우예요.
  ✅ 해결법: 공식 문서에서 제공하는 정확한 변수 이름을 복사해서 사용하세요.
• ❌ 이미지 버전 미지정 → latest만 써서 갑자기 설정이 깨져요.
  ✅ 해결법: nginx:1.21처럼 숫자가 포함된 버전을 사용하세요.