도커 컴포즈 사용법, 파일과 명령어 정리

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

오늘의 인사이트 요약

1. 도커 컴포즈는 웹앱·DB 컨테이너를 compose.yaml 한 파일로 함께 띄웁니다.

2. 도커 컴포즈 사용법은 services·ports·volumes·environment 네 항목과 up·down·logs·ps 네 명령어로 시작합니다.

3. 컴포즈는 한 서버의 컨테이너 관리에 쓰이며, 여러 서버의 배치·복구가 필요하면 쿠버네티스 같은 도구를 검토합니다.

도커 컴포즈는 여러 컨테이너의 실행 설정을 YAML 파일에 담아 함께 관리하는 도구입니다. 웹앱과 DB의 버전·포트·저장 위치를 공유할 수 있어 개발 환경을 맞추기 편합니다. 오늘은 도커 컴포즈 사용법을 파일 구조와 핵심 명령어, PostgreSQL 연결 예시로 알아보겠습니다.

도커란 무엇이고, 컴포즈는 왜 따로 쓸까요

도커는 앱을 실행 환경째 묶어 옮기는 도구입니다.

코드와 런타임을 이미지로 묶고 그 이미지를 실행한 것이 컨테이너라, 노트북과 서버에서 실행 환경을 맞추기 쉬워집니다. CPU 아키텍처와 볼륨·네트워크 설정은 별도로 맞춥니다.

컨테이너가 둘을 넘으면 명령어보다 파일이 편합니다.

포트와 저장 위치를 파일에 적어 두면 한 명령으로 함께 실행할 수 있습니다.

도커 컴포즈 설치는 이미 되어 있을지도 모릅니다

Docker Desktop을 깔았다면 도커 컴포즈 설치는 끝난 셈입니다.

Docker 공식 문서상 Desktop에 Compose가 들어 있으니 docker compose version으로 확인만 하면 됩니다. 직원 250명 이상이거나 연 매출 1,000만 달러 이상인 조직은 유료 구독 대상입니다.

리눅스 서버에는 플러그인을 따로 깝니다.

Ubuntu에서는 Docker 공식 패키지 저장소를 설정한 뒤 docker-compose-plugin 패키지를 설치합니다. 하이픈을 넣은 docker-compose는 2023년 7월 업데이트가 멈춘 V1 명령입니다.

도커 컴포즈 파일 compose.yaml, 웹앱과 DB로 읽어 봅니다

도커 컴포즈 사용법은 compose.yaml 파일에서 출발하는데, 최상위 version 항목은 현재 스키마 선택에 사용되지 않으며 오래된 항목이라는 경고가 표시됩니다. 아래는 웹앱 Dockerfile과 DB_PASSWORD 환경 변수가 준비되어 있다는 조건의 구성 예시입니다.

services:
  web:
    build: .
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - db-data:/var/lib/postgresql/data
volumes:
  db-data:

services에는 띄울 컨테이너를 하나씩 적습니다.

web은 Dockerfile로 빌드하고 db는 공개 이미지를 받습니다. 서로 이름으로 찾으니 DB 주소는 db면 됩니다.

ports는 바깥에서 들어올 문을 엽니다.

예시의 "127.0.0.1:3000:3000"은 내 컴퓨터의 로컬 주소에서 컨테이너 3000번 포트로 연결합니다. 제공 도식의 "3000:3000"은 기본적으로 모든 호스트 인터페이스에 게시하므로 공개 범위가 다릅니다.

volumes를 지정해야 DB 데이터가 남습니다.

이름 붙은 볼륨에 두면 컨테이너를 다시 만들어도 데이터는 그대로입니다.

environment의 비밀번호는 .env로 뺍니다.

${DB_PASSWORD}에는 같은 폴더 .env 값이 들어갑니다. 짧은 형식의 depends_on은 DB 접속 준비까지 기다리지 않습니다. 예시처럼 healthcheck와 service_healthy 조건을 함께 두면 DB 상태 확인 뒤 웹앱을 시작합니다. .env는 저장소에 올리지 않습니다.

도커 컴포즈 명령어는 이 네 개로 시작합니다

코드를 고쳤다면 up -d --build로 다시 빌드하면 되고, down에 -v를 붙이면 DB 볼륨까지 지웁니다.

도커 컴포즈 쿠버네티스 차이, 언제 넘어갈까요

컴포즈는 서버 한 대 안의 컨테이너를 묶습니다.

개발 환경이나 테스트 서버, 초기 서비스에 맞습니다.

쿠버네티스는 여러 서버에 나눠 띄우고 상태를 지킵니다.

서버가 죽으면 다른 곳에 다시 띄우고 개수도 늘리지만 운영 부담이 큽니다. 도커 컴포즈 쿠버네티스 차이는 서버를 여러 대 쓰는지, 장애를 자동으로 복구해야 하는지로 정리됩니다.

우리 서비스가 서버 한 대로 버티지 못하는 때는 언제인가요? 이 답이 보이기 전까지는 도커 컴포즈 사용법만 익혀도 배포가 가벼워집니다.

구체적인 설정과 사용 조건은 Compose 시작 순서와 healthcheck · Docker Desktop 구독 조건에서 더 자세히 보실 수 있습니다.

개발 환경과 서비스 운영을 함께 살펴봅니다

똑똑한개발자는 웹·앱과 관리자 시스템의 기획·디자인·개발·운영을 함께하는 팀입니다. Python·Django·AWS 등을 활용해 백엔드와 인프라를 구성합니다. 서비스의 기능뿐 아니라 데이터 저장 위치와 배포 환경도 함께 살펴야 개발 중 만든 설정을 운영에 이어 쓰기 편합니다.

현재 서비스에 어떤 실행 환경이 적합할지 고민되시나요? 아래 똑똑한개발자 링크로 문의해 주시면 웹앱·DB 구성과 배포 후 관리 범위를 함께 검토하겠습니다.

감사합니다. :)

📚 이어서 읽어보세요

• 환경변수와 .env 설정 방법

• 가비아 도메인 Vercel 연결 방법