빠른 흐름

services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

docker compose up -d --build
docker compose ps
docker compose down

기본 흐름

어떤 Compose 흐름을 먼저 떠올리면 되나

services / networks / volumes — Compose 파일의 세 최상위 키가 멀티컨테이너 앱을 선언한다

services는 실행할 컨테이너 목록을, networks는 컨테이너 간 통신 규칙을, volumes는 영속 저장소를 정의합니다. Compose는 이 선언을 읽어 docker run, docker network create, docker volume create에 해당하는 작업을 순서대로 대신 실행합니다. 별도로 networks를 선언하지 않으면 Compose가 프로젝트 단위 기본 네트워크를 자동 생성합니다.

services:
  app:
    image: my-app
  db:
    image: postgres:16

# 명시적 네트워크 없이도 app에서 db로 접속 가능
# host: "db", port: 5432

docker compose up과 down — 스택 전체를 한 번에 올리고 내린다

docker compose up -d는 이미지 빌드(필요 시), 네트워크 생성, 볼륨 생성, 컨테이너 실행을 순서대로 처리합니다. docker compose down은 컨테이너와 네트워크를 제거하지만 볼륨은 기본적으로 남겨 데이터가 유지됩니다. 볼륨까지 삭제하려면 --volumes 플래그가 필요합니다.

# 빌드 + 시작
docker compose up -d --build

# 로그 확인
docker compose logs -f app

# 정지 및 컨테이너/네트워크 제거 (볼륨 유지)
docker compose down

# 볼륨까지 전부 삭제
docker compose down --volumes

서비스 이름으로 통신 — 같은 Compose 파일 내 서비스끼리는 서비스 이름이 호스트명이 된다

Compose가 생성하는 기본 네트워크 안에서 각 서비스의 컨테이너 이름이 DNS 호스트명으로 등록됩니다. app 서비스에서 db로 접근하려면 postgres://db:5432/mydb처럼 서비스 이름을 호스트명으로 쓰면 됩니다. 별도 IP 조회 없이 서비스 이름만으로 통신이 됩니다.

services:
  app:
    environment:
      DATABASE_URL: postgres://db:5432/mydb  # 서비스 이름 "db"를 호스트로 사용
  db:
    image: postgres:16

Compose는 여러 docker run을 선언형으로 묶는 도구다

컨테이너 하나만 빠르게 띄울 땐 docker run이 더 직접적입니다. 반대로 앱, DB, 볼륨, 네트워크를 같이 관리해야 하면 Compose가 훨씬 안전합니다. 수동 docker run을 여러 번 치면 포트, 환경 변수, 볼륨, 네트워크가 서로 흩어져 재현이 어려워지기 쉽습니다.

체크포인트

주의할 점

services:
  app:
    environment:
      DATABASE_URL: postgres://localhost:5432/mydb

# Compose 네트워크 안에서 localhost는 app 자신이므로
# db 컨테이너로 연결되지 않음