도커 컴포즈 사용법 실전 가이드: 명령어와 다중 컨테이너 배포
문법을 배웠으니 이제 실전이다. 명령어 한 줄에 여러 개의 서버가 동시에 살아 숨 쉬는 마법을 직접 경험해 보자.
이 글은 2026년 7월 기준으로 작성됐다. 최신 명령어 옵션은 언제나 Docker Compose CLI 레퍼런스를 함께 확인하는 것이 좋다.
이 글은 'Docker Compose 마스터' 시리즈의 마지막인 3편이다. 지난 시간에 다룬 docker-compose.yml 작성법이 헷갈린다면 2편: 도커 컴포즈 작성법 완벽 가이드를 먼저 읽고 오는 것을 권장한다.
이번 편에서는 백엔드 API, 데이터베이스, 그리고 캐시 메모리까지 포함된 다중 컨테이너 실전 배포 환경을 직접 구성하고, 이를 제어하는 데 필요한 필수 명령어들을 총정리한다.
실전 다중 컨테이너 환경 아키텍처
실무에서 가장 흔하게 접할 수 있는 3-Tier 기반의 서비스 구성을 가정해 보겠다. 우리가 띄울 컨테이너들은 다음과 같다.
- Backend (Node.js/Spring 등): 실제 비즈니스 로직을 처리하는 API 서버
- Database (PostgreSQL): 영구적인 유저 데이터를 저장하는 RDBMS
- Cache (Redis): 세션이나 빠른 데이터 조회를 위한 인메모리 캐시
이 세 가지 서비스가 어떻게 엮이는지 docker-compose.yml 코드를 통해 살펴보자.
실전 docker-compose.yml 배포 예제
version: '3.8'
services:
backend:
image: my-backend-api:latest # 사전에 빌드된 이미지 가정
ports:
- "8080:8080"
environment:
- DB_HOST=postgres-db
- REDIS_HOST=redis-cache
- DB_USER=admin
- DB_PASS=secret
depends_on:
- postgres-db
- redis-cache
networks:
- app-network
postgres-db:
image: postgres:15-alpine
environment:
- POSTGRES_USER=admin
- POSTGRES_PASSWORD=secret
volumes:
- db-data:/var/lib/postgresql/data
networks:
- app-network
redis-cache:
image: redis:7-alpine
networks:
- app-network
volumes:
db-data:
networks:
app-network:
driver: bridge
이 파일을 프로젝트 루트 디렉토리에 저장했다면, 배포 준비는 모두 끝났다. backend 컨테이너는 환경 변수로 postgres-db와 redis-cache라는 서비스명을 직접 참조하여 통신하게 되며, app-network라는 동일한 네트워크에 속해있기 때문에 원활한 데이터 교환이 가능하다. DB 데이터는 db-data 볼륨 덕분에 안전하게 유지된다.
도커 컴포즈 필수 명령어 핵심 정리
파일이 준비되었으니 이제 터미널을 열고 애플리케이션을 조작해 볼 차례다. 개발자가 매일같이 숨 쉬듯 사용하는 핵심 명령어 4가지를 정리했다.
1. 실행하기: docker compose up
작성한 YAML 파일을 읽어 컨테이너들을 생성하고 실행한다.
# 백그라운드에서 실행 (가장 많이 씀)
$ docker compose up -d
# 이미지를 강제로 다시 빌드하고 싶을 때
$ docker compose up -d --build
-d (detach) 옵션을 주면 컨테이너가 백그라운드에서 돌기 때문에 터미널을 계속 사용할 수 있다.
2. 상태 확인하기: docker compose ps
현재 디렉토리의 docker-compose.yml로 띄운 서비스들의 가동 상태(Up, Exited 등)와 개방된 포트 정보를 한눈에 보여준다.
$ docker compose ps
3. 로그 실시간 확인: docker compose logs
애플리케이션에 에러가 났을 때 가장 먼저 쳐야 할 명령어다. 전체 컨테이너의 로그를 보여주며, 특정 서비스의 로그만 볼 수도 있다.
# 전체 서비스의 실시간 로그 모니터링
$ docker compose logs -f
# backend 서비스의 로그만 실시간으로 보기
$ docker compose logs -f backend
4. 종료 및 리소스 정리: docker compose down
단순히 컨테이너를 멈추는 것(stop)을 넘어, 컨테이너를 삭제하고 컴포즈가 만들었던 기본 네트워크까지 깔끔하게 제거한다. (단, 볼륨은 삭제되지 않아 데이터는 보존된다.)
# 서비스 완전 종료 및 네트워크 정리
$ docker compose down
# 볼륨(데이터)까지 완전히 초기화하고 싶을 때 (주의해서 사용)
$ docker compose down -v
자주 묻는 질문 (FAQ)
Q. 구동 중인 컨테이너 내부로 들어가서(Shell) 리눅스 명령어를 치고 싶어요.
A. docker compose exec 명령어를 사용하면 된다. 예를 들어 backend 컨테이너의 셸로 접속하려면 docker compose exec backend /bin/sh (또는 /bin/bash)를 입력한다.
Q. 특정 컨테이너 하나만 재시작할 수 있나요?
A. 가능하다. 전체를 내릴 필요 없이 docker compose restart backend처럼 서비스 이름을 뒤에 붙여주면 해당 컨테이너만 빠르게 재시작된다. 설정 파일을 살짝 바꾼 후 유용하게 쓰인다.
📝 정리
이번 글에서 다룬 핵심 내용:
- [x] 실전 3-Tier 아키텍처 배포를 위한
docker-compose.yml을 작성했다. - [x]
up -d명령어로 전체 시스템을 단번에 백그라운드에서 띄우는 방법을 익혔다. - [x]
logs,ps,down등 실무에서 트러블슈팅과 관리에 쓰이는 핵심 명령어를 파악했다.
이로써 도커 컴포즈란 무엇인지 알아보았던 1편부터 시작된 'Docker Compose 마스터' 시리즈는 여기까지다. 개념부터 실전까지, 이제 복잡한 서버 환경도 명령어 한 줄로 통제하는 강력한 권한을 손에 쥐게 되었다. 지금 당장 터미널을 열고 직접 자신만의 아키텍처를 띄워보길 바란다.
