Docker Compose: 하나의 명령으로 여러 서비스 실행하기

단일 서비스는 긴 docker run 명령어 하나로 시작할 수 있어요. 서로를 봐야 하는 두 서비스가 되면 그 방식은 더 이상 통하지 않아요. 다음 날이면 매개변수를 잊어버리게 되니까요. Compose는 전체 설명을 읽고, 편집하고, 저장소에 보관할 수 있는 파일 하나로 옮겨줘요.

최소 예시

/opt/myapp 디렉터리에 compose.yaml이 들어 있어요.

services:
  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5

  app:
    image: ghcr.io/example/app:1.4.2
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/app
    ports:
      - "127.0.0.1:8080:8080"

volumes:
  db-data:

그 옆에 .env 파일이 있어요.

DB_PASSWORD=long-random-password

chmod 600 .env
docker compose up -d
docker compose ps
docker compose logs -f app

여기서 중요한 것

• 주소 대신 이름. 애플리케이션은 db라는 이름으로 데이터베이스에 접근해요. Compose는 서비스 이름이 자동으로 확인되는 공유 네트워크를 만들어요. 데이터베이스 포트를 외부에 공개할 필요도 없고, 공개해서도 안 돼요.
• restart: unless-stopped. 이게 없으면 머신이 재부팅된 뒤 아무것도 다시 올라오지 않아요.
• 헬스 체크가 있는 depends_on. 일반적인 depends_on은 컨테이너가 시작되기만을 기다릴 뿐, 데이터베이스가 연결을 받을 준비가 됐는지는 기다리지 않아요. 애플리케이션이 더 일찍 시작해서 죽어버려요.
• 정확한 이미지 버전. postgres:latest가 아니라 postgres:17이에요. latest를 쓰면 언젠가 다음 pull에서 예전 데이터를 열지 못하는 메이저 버전이 올라와요.
• 127.0.0.1에 공개하기. 포트를 외부에 노출할 때는 인증서가 있는 웹 서버를 통해서만 하세요.

일상적인 명령어

docker compose up -d          # bring up or apply changes
docker compose down           # stop and remove containers (volumes intact)
docker compose down -v        # ...and remove volumes too
docker compose restart app    # restart one service
docker compose exec app sh    # go inside
docker compose pull && docker compose up -d   # update images
docker compose config         # show final file with substitutions

docker compose config는 시작하기 전에 파일을 확인하는 가장 좋은 방법이에요. 변수가 무엇으로 확장됐는지, 들여쓰기가 어디서 깨졌는지 보여줘요.

docker compose down -v는 데이터베이스와 함께 볼륨을 삭제해요. 되돌릴 수 없어요. -v가 들어간 작업을 하기 전에는 반드시 복사본이 있는지 확인하세요. 백업을 참고하세요.

환경 파일

같은 스택을 테스트용과 프로덕션용으로 나눌 때는 오버레이를 쓰면 편해요.

docker compose -f compose.yaml -f compose.prod.yaml up -d

두 번째 파일은 차이점만 덮어써요. 메모리 제한, 공개 포트, 로그 레벨 같은 것들이요.

흔한 실수

• 저장소에 보관하는 compose.yaml에 들어 있는 비밀 값. 비밀 값은 권한 600인 .env에 두고 커밋하지 마세요.
• docker-compose와 docker compose를 섞어 쓰기. 예전 v1 버전은 일부 문법을 이해하지 못하고 프로젝트를 다른 이름으로 저장해요. 플러그인을 설치하세요. Docker 설치를 참고하세요.
• 볼륨 대신 컨테이너 안에 데이터 두기. docker compose down 후에 사라져요. 볼륨을 참고하세요.
• 메모리 제한 없음. 서비스 하나가 머신의 메모리를 전부 먹으면 커널이 그 이웃들을 죽여버려요. 리소스 제한을 참고하세요.