Docker Compose: 여러 컨테이너 묶어 띄우기

Docker Compose란

docker run은 컨테이너 하나를 띄운다. 실제 서비스는 웹 서버, 애플리케이션, DB처럼 여러 컨테이너가 서로 통신하며 동작하므로, 각각의 이미지·포트·환경 변수·볼륨·네트워크를 매번 긴 명령으로 맞추기 어렵다. Docker Compose는 이 구성을 YAML 파일 하나(compose.yaml)에 선언하고 docker compose up 한 번으로 전부 띄우는 도구다.

• 한 대의 호스트에서 여러 컨테이너를 묶어 관리한다. 여러 서버에 걸친 배치·자동 복구는 쿠버네티스 같은 오케스트레이터의 몫이다(VM과 컨테이너).
• 현재 Compose는 Docker CLI 플러그인 docker compose(띄어쓰기)다. 예전의 독립 실행 파일 docker-compose(하이픈)는 지원이 끝났다.
• 파일 맨 위의 version: 키는 더 이상 쓰이지 않는다. 적어도 무시되고 경고만 나온다.
• 과거에는 Orchard의 fig(fig.yml, fig up)였다. 2014년 Docker가 Orchard를 인수해 fig가 Python으로 된 Compose v1(docker-compose)이 되었고, 지금의 Go로 다시 쓴 v2 플러그인으로 이어졌다. 당시 서비스끼리는 links로 잇고 데이터는 volumes_from으로 공유했는데, 둘 다 레거시가 되어 기본 네트워크의 서비스 이름 DNS와 이름 있는 볼륨으로 바뀌었다. 여러 호스트로 넓히는 일은 Compose가 아니라 Swarm 스택과 쿠버네티스의 몫으로 정리됐다.

docker run 명령을 여러 번 치는 것과 비교한 장점은 구성이 코드로 남아 버전 관리되고, 네트워크·볼륨이 자동으로 만들어지고 이어지며, up·down 한 번으로 전체를 만들고 지우고, 팀원 누구나 같은 개발 환경을 띄운다는 것이다.

예시: Nginx + PHP-FPM + MariaDB

services:
  nginx:
    build: ./requirements/nginx        # 이 폴더의 Dockerfile로 이미지 빌드
    ports: ["443:443"]                 # 호스트 443 → 컨테이너 443. 외부에 공개되는 유일한 서비스
    volumes: [wordpress:/var/www/html]
    depends_on: [wordpress]
    restart: unless-stopped
    networks: [backend]
 
  wordpress:
    build: ./requirements/wordpress
    expose: ["9000"]                   # 같은 네트워크의 컨테이너에만 문서상 공개
    env_file: .env
    volumes: [wordpress:/var/www/html]
    depends_on:
      mariadb:
        condition: service_healthy     # DB가 healthcheck를 통과한 뒤 시작
    restart: unless-stopped
    networks: [backend]
 
  mariadb:
    build: ./requirements/mariadb
    env_file: .env
    volumes: [db:/var/lib/mysql]
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect"]
      interval: 5s
    restart: unless-stopped
    networks: [backend]
 
volumes:
  wordpress:
  db:
 
networks:
  backend:
    driver: bridge

웹 요청은 Nginx가 받고, .php 요청은 FastCGI로 wordpress:9000의 PHP-FPM에 넘긴다. 같은 Compose 네트워크 안에서는 서비스 이름이 곧 호스트 이름이 되므로 IP 대신 wordpress, mariadb로 서로를 찾는다. Nginx가 정적 파일과 PHP 요청을 나누는 구조는 웹 서버, WAS, 그리고 Nginx의 리버스 프록시와 같다.

서비스의 주요 키

환경 변수 관리

services:
  api:
    image: "acme/api:${API_TAG:-latest}"   # .env나 셸 환경 변수로 치환, 없으면 기본값
    env_file: [.env.api]                  # 컨테이너 안으로
    environment:
      LOG_LEVEL: info                     # env_file보다 우선

같은 변수가 여러 곳에 있으면 컨테이너 안의 값은 docker compose run -e > environment > env_file > 이미지의 ENV 순으로 정해진다. 치환에서는 셸의 환경 변수가 .env 파일보다 우선한다. 다른 파일을 쓰려면 docker compose --env-file .env.prod up을 쓴다. 비밀번호가 든 파일은 .gitignore에 넣고, 운영에서는 아래 secrets를 쓴다.

시작 순서와 healthcheck

depends_on은 시작 순서를 정한다. 기본형(depends_on: [db])은 db 컨테이너가 시작되기만 하면 api를 띄운다. DB 프로세스가 연결을 받을 준비가 됐는지는 기다리지 않아, 앱이 첫 연결에 실패하는 일이 흔하다.

services:
  api:
    depends_on:
      db:
        condition: service_healthy            # db의 healthcheck가 healthy가 된 뒤
        restart: true                         # db가 다시 시작되면 api도 다시 시작
      migrate:
        condition: service_completed_successfully   # 마이그레이션이 0으로 끝난 뒤
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
  migrate:
    image: acme/api:1.4.2
    command: ["npm", "run", "migrate"]
    depends_on: { db: { condition: service_healthy } }

한계도 있다. depends_on은 처음 띄울 때의 순서만 다루고, 실행 중에 DB가 잠깐 끊기는 상황은 막지 못한다. 앱이 연결 재시도를 갖춰야 한다. 또 Compose는 한 호스트 안의 순서만 다룬다. healthcheck 옵션의 뜻은 Dockerfile 노트의 HEALTHCHECK와 같다.

네트워크

Compose는 따로 정하지 않아도 프로젝트마다 기본 bridge 네트워크(<프로젝트>_default)를 하나 만들고 모든 서비스를 붙인다. 이것은 사용자 정의 네트워크라서 Docker 내장 DNS가 서비스 이름을 IP로 풀어 준다. 서비스를 여러 개로 늘리면 같은 이름에 IP가 여러 개 돌아와 라운드 로빈된다.

services:
  web: { networks: [front] }
  api: { networks: [front, back] }       # 두 네트워크 모두에 붙어 중계
  db:  { networks: [back] }              # web에서는 db가 보이지 않는다
networks:
  front:
  back:
    internal: true                       # 외부로 나가는 경로 없음

네트워크를 나누면 서비스 간 접근 범위를 제한할 수 있다. 서버 프로세스가 127.0.0.1에만 바인드되어 있으면 다른 컨테이너에서 접근할 수 없다. 컨테이너 안에서는 0.0.0.0(모든 인터페이스)으로 듣게 하고, 외부 노출은 ports로 통제한다. 드라이버(bridge·host·overlay·none)의 차이, 내장 DNS, 포트 공개의 원리는 Docker 네트워크와 볼륨에 있다.

볼륨: 데이터를 컨테이너 밖에 두기

컨테이너를 지우면 그 안에 쓴 데이터도 사라진다. DB 파일이나 업로드처럼 남겨야 할 데이터는 마운트로 밖에 둔다. 운영 데이터는 최상위 volumes에 선언한 named volume, 개발 중 소스 코드는 bind mount(./src:/app/src), 남기면 안 되는 임시 데이터는 tmpfs를 쓴다. 세 방식의 차이와 볼륨 수명·드라이버는 Docker 네트워크와 볼륨에 있다.

named volume을 쓰면서 저장 위치를 호스트의 정해진 폴더로 지정하고 싶으면 local 드라이버 옵션으로 bind한다.

volumes:
  db:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /home/user/data/db      # 미리 만들어 둔 폴더여야 한다

서비스 간 볼륨 공유

같은 named volume을 여러 서비스에 마운트하면 데이터를 함께 쓴다. 위 예시에서 wordpress 볼륨을 Nginx와 PHP-FPM이 함께 쓰는 것이 그 예다. 읽기만 하는 쪽은 :ro를 붙인다.

services:
  app:    { volumes: [uploads:/srv/uploads] }
  backup: { volumes: [uploads:/data:ro] }
volumes:
  uploads:

다른 컨테이너의 볼륨을 통째로 물려받는 volumes_from도 있지만, 무엇이 공유되는지 파일에서 드러나지 않고 상대 서비스의 마운트 구성에 묶인다. 공유할 볼륨에 이름을 붙여 명시적으로 마운트하는 방식이 그 대안이다.

여러 Compose 파일 겹치기

공통 구성은 compose.yaml에 두고 환경별 차이만 다른 파일로 덮는다.

겹칠 때 image·command 같은 단일 값은 교체되고, environment·labels는 키별로, volumes는 컨테이너 경로별로 병합되며, ports·expose 같은 목록은 이어 붙는다. 결과가 헷갈리면 docker compose -f … config로 최종 구성을 확인한다.

스케일링

docker compose up -d --scale worker=3     # 또는 서비스에 deploy.replicas: 3

비밀 값: secrets

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password   # 공식 이미지는 *_FILE 변수를 지원
    secrets: [db_password]
secrets:
  db_password:
    file: ./secrets/db_password.txt

secrets는 값을 환경 변수가 아니라 컨테이너의 /run/secrets/<이름> 파일로 넣어, docker inspect나 자식 프로세스 환경에 노출되지 않게 한다. Swarm에서는 같은 문법이 암호화된 Swarm secrets로 동작한다(Docker 컨테이너 운영).

점검과 디버깅

docker compose config        # 변수 치환이 끝난 최종 설정 출력. YAML 문법 오류도 여기서 잡힌다
docker compose up -d --build # 이미지를 다시 빌드하고 백그라운드로 띄우기
docker compose ps            # 서비스별 상태
docker compose logs -f wordpress
docker compose exec mariadb sh
docker compose down          # 컨테이너·네트워크 삭제 (볼륨은 남는다. -v를 주면 볼륨까지)
docker network ls; docker volume ls

정리

• Compose는 여러 컨테이너의 구성을 YAML 하나로 선언하고 docker compose up으로 띄운다. version: 키와 docker-compose는 옛 방식이다.
• 같은 네트워크에서는 서비스 이름으로 통신한다. 외부 공개는 ports, 내부용은 expose.
• depends_on은 시작 순서일 뿐이다. 준비 완료를 기다리려면 healthcheck를 건다.
• 남길 데이터는 named volume, 개발 중 코드 공유는 bind mount. 볼륨 공유는 volumes_from 대신 이름 붙은 볼륨으로.
• .env는 Compose 파일의 치환용, env_file·environment는 컨테이너용이다. 비밀은 secrets로 파일로 넣는다.
• 환경별 차이는 override 파일·-f 겹치기로, 스케일링은 고정 이름·고정 호스트 포트를 피해서 한다.

관련 노트: Dockerfile 작성과 컨테이너의 PID 1, Docker 네트워크와 볼륨, Docker 컨테이너 운영, VM과 컨테이너, 웹 서버, WAS, 그리고 Nginx