[Docker 시리즈 6편] Docker Compose 기본기와 작은 실습

5편에서 이미지를 만들었다면 이제 "여러 컨테이너를 어떻게 동시에 실행할지"를 고민할 차례입니다. Docker Compose는 docker-compose.yml 한 장으로 서비스, 네트워크, 볼륨을 선언하는 도구입니다. 이번 글에서는 nginx 정적 사이트 + MySQL 데이터베이스 같은 친숙한 구조를 예로 들어 기본기를 익힙니다.

이 글의 흐름

Compose가 어떤 문제를 해결하는지 머릿속 모델 세우기
웹+DB 두 컨테이너를 정의하는 가장 작은 Compose 예제
초보자가 꼭 만져 봐야 할 명령(up, down, logs, ps)
볼륨·환경변수·네트워크 선언을 읽는 방법
초보자가 Compose에서 가장 먼저 익혀야 할 감각

읽기 카드

예상 소요 시간: 16분

사전 준비: Dockerfile로 이미지를 빌드해 본 경험

읽고 나면: Compose 파일을 직접 작성하고 두 컨테이너를 동시에 띄울 수 있습니다.

머릿속 모델: 전선 정리 멀티탭

컨테이너를 멀티탭에 꽂는다고 상상해 봅시다.

services: 멀티탭에 꽂는 전자기기 (web, db 등)
networks: 기기들이 서로 대화하는 전선 묶음
volumes: 기기가 끄더라도 남겨 두는 저장소

각 항목을 YAML로 적어 두면 docker compose up 한 번으로 전원을 켰다 끌 수 있습니다. 이게 Compose가 해결하는 가장 큰 문제입니다.

웹+DB Compose 예제

가장 많이 만나는 구조는 "정적 웹서버 + MySQL" 또는 "Node 앱 + Redis"입니다. 아래 예제는 nginx 정적 사이트와 MySQL을 한 번에 정의한 것입니다.

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./public:/usr/share/nginx/html:ro
    networks:
      - app-net

  db:
    image: mysql:8.4
    environment:
      - MYSQL_ROOT_PASSWORD=your-root-password
      - MYSQL_DATABASE=school
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - app-net

volumes:
  db-data:

networks:
  app-net:
    driver: bridge

이 한 장에서 이미 아래 정보를 모두 확인할 수 있습니다.

web 서비스는 정적 파일을 읽기 전용 볼륨으로 마운트하고, 외부 8080 포트를 80번과 연결합니다.
db 서비스는 환경 변수를 통해 초기 설정을 만들고, 데이터를 db-data 볼륨에 저장합니다.
두 서비스 모두 app-net 네트워크에 묶였으므로, 같은 네트워크 안의 다른 컨테이너에서는 db:3306으로 바로 접속할 수 있습니다.

터미널에서 따라 하는 Compose 기본 명령

파일을 저장한 뒤 docker compose up -d를 실행하면 두 서비스가 백그라운드에서 실행됩니다. 최신 Docker Desktop 환경에서는 보통 docker-compose보다 docker compose 명령을 사용합니다.
docker compose ps로 컨테이너 이름, 포트, 상태를 확인합니다.
docker compose logs -f web으로 웹 서버 로그만 실시간으로 봅니다.
"멈추고 싶을 때"는 docker compose down으로 컨테이너와 네트워크를 정리합니다.
데이터를 남기고 싶다면 down 이후에도 volumes 블록에 선언한 이름이 유지됩니다. db-data는 다음 up 때 다시 마운트됩니다. 반대로 docker compose down -v를 쓰면 이름 있는 볼륨도 함께 지워집니다.

Mini Lab: web 서비스의 ports를 9090:80으로 바꾸고 docker compose up -d --build를 실행해 보세요. http://localhost:9090으로 접속해야 한다는 사실이 체감되면 포트 매핑 개념이 확실히 자리 잡습니다.

볼륨·환경변수·네트워크를 읽는 체크리스트

volumes: 이름 있는 볼륨(db-data)은 데이터를 영구 보관합니다. 경로 마운트(./public)는 로컬 폴더 변화를 즉시 반영합니다.
environment: 데이터베이스 초기 설정, API 키, 애플리케이션 모드를 정의합니다. 민감한 값은 Compose 파일에 직접 적기보다 .env 파일이나 env_file로 분리하는 편이 안전합니다.
networks: 기본값은 bridge입니다. 여러 네트워크를 선언해 web만 외부 리버스 프록시와 대화하게 만들거나, db를 내부망에만 두는 방식으로 확장할 수 있습니다.

여기서 중요한 점 하나를 더 기억하세요. db 같은 서비스 이름은 같은 Compose 네트워크 안의 컨테이너끼리만 사용할 수 있습니다. 내 맥 터미널에서는 db:3306 대신 보통 localhost:3306처럼 공개한 포트로 접근합니다.

Compose 파일을 처음 읽을 때는 이 세 가지 블록을 먼저 찾으세요. 나머지 세부 옵션은 대부분 이 구조 위에 얹힌 장식입니다.

초보자가 Compose에서 가장 먼저 익혀야 할 감각

Compose를 처음 배울 때는 아래 세 가지만 확실히 구분하면 됩니다.

서비스: 무엇을 띄우는가
네트워크: 누가 누구와 대화하는가
볼륨: 무엇을 껐다 켜도 남겨 둘 것인가

즉, Compose 기본기를 먼저 이해하면 어떤 프로젝트의 docker-compose.yml도 빠르게 해석할 수 있습니다. 다음 7편에서는 이 파일 안에서 운영용 컨테이너와 개발용 컨테이너가 왜 다른지, Node 앱을 예로 들어 더 자세히 비교합니다.