빠른 흐름

docker compose -p myapp-dev up -d

COMPOSE_PROJECT_NAME=myapp-ci-123 docker compose up -d

docker compose ls
docker compose -p myapp-dev down

이름 구조

project name은 Compose 리소스 격리 단위다

Compose는 하나의 compose.yaml을 project로 보고, project name을 기준으로 컨테이너, 네트워크, 볼륨 이름을 만듭니다. 기본값은 Compose 파일이 있는 디렉터리 이름입니다. 같은 디렉터리에서 같은 파일을 올리면 같은 project로 취급되므로 기존 리소스를 재사용하거나 덮어쓰는 것처럼 보일 수 있습니다.

project: shop
service: web

컨테이너 예: shop-web-1
네트워크 예: shop_default
볼륨 예: shop_pgdata

로컬 개발에서는 큰 문제가 없지만, CI나 여러 브랜치를 동시에 띄우는 환경에서는 project name을 명시해야 충돌을 줄일 수 있습니다.

project name 우선순위는 명시적인 값이 이긴다

project name은 여러 방법으로 지정할 수 있고, 더 명시적인 값이 우선합니다. 가장 직접적인 방법은 -p 플래그입니다. 환경 변수 COMPOSE_PROJECT_NAME도 CI에서 자주 씁니다. Compose 파일의 top-level name:은 저장소에 기본 이름을 남기고 싶을 때 적합합니다.

name: shop

services:
  web:
    image: nginx:alpine

docker compose -p shop-feature-login up -d

-p를 쓰면 파일 안 name:보다 우선하므로, 같은 Compose 파일을 브랜치별·테스트별로 격리해서 실행할 수 있습니다.

service name과 container_name은 다르게 관리한다

서비스끼리 통신할 때는 Compose 네트워크 안에서 service name을 호스트명으로 쓰면 됩니다. 이때 container_name을 고정해 이름을 직접 박아 넣으면 같은 Compose 파일을 여러 번 띄울 때 충돌하기 쉽습니다.

services:
  api:
    image: my-api
    environment:
      DATABASE_URL: postgres://db:5432/app
  db:
    image: postgres:16

특별한 이유가 없다면 container_name을 피하고, project name과 service name 조합이 만든 기본 이름을 그대로 쓰는 편이 더 재현성이 좋습니다.

언제 지정할까

주의할 점

project name은 소문자, 숫자, dash, underscore 중심의 제한을 받습니다. 브랜치명을 그대로 넣으면 slash나 대문자 때문에 실패할 수 있으므로 CI에서는 안전한 이름으로 정규화해서 넘겨야 합니다.