[스프링] 7. Docker Compose로 전체 시스템 실행하기

이전 편에서 Spring Boot 서비스 3개와 Nginx API Gateway를 각각 만들었다. 이번 편에서는 Docker Compose로 이 4개의 컨테이너를 한 번에 띄우고, 테스트 대시보드로 전체 시스템이 정상 동작하는지 검증한다.

왜 Docker Compose가 필요한가

4개의 서비스를 각각 docker build하고 docker run으로 실행하려면, 매번 8개의 명령어를 타이핑해야 한다. 네트워크 설정, 환경 변수, 실행 순서까지 신경 쓰면 관리가 복잡해진다.

Docker Compose는 이 모든 것을 하나의 YAML 파일로 정의한다. docker compose up 한 줄이면 빌드부터 네트워크 연결까지 전부 처리된다.

docker-compose.yml 작성하기

단계 1 — 백엔드 서비스 정의

프로젝트 루트에 docker-compose.yml을 만든다. 백엔드 3개 서비스부터 작성한다.

services:
  user-service:
    build:
      context: ./user-service
      dockerfile: Dockerfile
    container_name: user-service
    networks:
      - microservices-network
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - SERVER_PORT=8081
    healthcheck:
      test: ["CMD", "curl", "-f",
             "http://localhost:8081/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  order-service:
    build:
      context: ./order-service
      dockerfile: Dockerfile
    container_name: order-service
    networks:
      - microservices-network
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - SERVER_PORT=8082
    healthcheck:
      test: ["CMD", "curl", "-f",
             "http://localhost:8082/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  payment-service:
    build:
      context: ./payment-service
      dockerfile: Dockerfile
    container_name: payment-service
    networks:
      - microservices-network
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - SERVER_PORT=8083
    healthcheck:
      test: ["CMD", "curl", "-f",
             "http://localhost:8083/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

세 서비스 모두 같은 네트워크에 연결하고, ports 매핑이 없다는 점에 주목해야 한다. 외부에서 직접 접근할 수 없게 만든 것이다. Gateway를 통해서만 접근 가능하도록 하는 것이 API Gateway 패턴의 핵심이다.

container_name을 서비스 이름과 동일하게 지정하는 이유가 있다. Nginx 설정의 server user-service:8081에서 이 이름으로 DNS 조회를 하기 때문이다.

단계 2 — API Gateway 서비스 추가

백엔드 서비스 정의 위에 Gateway를 추가한다.

services:
  api-gateway:
    build:
      context: ./nginx
      dockerfile: Dockerfile
    container_name: api-gateway
    ports:
      - "80:80"
    depends_on:
      - user-service
      - order-service
      - payment-service
    networks:
      - microservices-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3

유일하게 ports를 선언하는 서비스다. 호스트의 80번 포트가 Gateway 컨테이너의 80번 포트와 연결된다. 브라우저에서 localhost에 접속하면 이 Gateway로 들어온다.

depends_on으로 세 서비스가 먼저 시작되도록 한다. 하지만 앞서 개념 편에서 다뤘듯이, 이것은 시작 순서만 보장할 뿐 서비스 준비 완료를 보장하지는 않는다.

단계 3 — 네트워크 정의

파일 하단에 네트워크를 정의한다.

networks:
  microservices-network:
    driver: bridge

bridge는 Docker의 기본 네트워크 드라이버다. 같은 네트워크에 연결된 컨테이너끼리 서비스 이름으로 DNS 해석이 가능해진다. user-service라는 이름으로 요청을 보내면 Docker DNS가 해당 컨테이너의 IP를 반환한다.

Spring Boot Dockerfile 작성

각 서비스의 루트에 Dockerfile을 만든다. 세 서비스 모두 같은 구조이고 포트만 다르다.

# 빌드 스테이지
FROM eclipse-temurin:17-jdk-jammy AS builder
WORKDIR /app
COPY gradlew .
COPY gradle gradle
COPY build.gradle .
COPY settings.gradle .
COPY src src
RUN chmod +x ./gradlew
RUN ./gradlew clean bootJar

# 실행 스테이지
FROM eclipse-temurin:17-jre-jammy
LABEL maintainer="Codeit"
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
EXPOSE 8081
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost:8081/actuator/health || exit 1
ENV JAVA_OPTS="-Xms256m -Xmx512m -XX:+UseG1GC -XX:+UseStringDeduplication"
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

order-service는 EXPOSE 8082, payment-service는 EXPOSE 8083으로 포트만 변경한다. HEALTHCHECK의 포트도 맞춰서 수정한다.

멀티스테이지 빌드의 효과를 다시 한번 확인해보면, 빌드 스테이지의 JDK, Gradle, 소스 코드는 최종 이미지에 포함되지 않는다. COPY --from=builder로 빌드된 JAR만 가져온다.

빌드 및 실행

단계 1 — 전체 빌드

프로젝트 루트에서 다음 명령을 실행한다.

docker compose build

4개의 이미지를 빌드한다. Spring Boot 서비스는 Gradle 빌드가 포함되므로 첫 빌드에 시간이 걸린다. 이후 소스 변경이 없으면 Docker 캐시가 작동해서 빠르게 끝난다.

단계 2 — 전체 시스템 실행

docker compose up -d

-d 플래그는 백그라운드 실행이다. 4개의 컨테이너가 순서대로 시작된다.

단계 3 — 상태 확인

docker compose ps

모든 서비스가 Up 상태이고 healthcheck가 healthy인지 확인한다. Spring Boot 서비스는 시작하는 데 10~30초 걸리므로, 처음에는 starting 상태일 수 있다.

docker compose logs -f api-gateway

특정 서비스의 로그를 실시간으로 볼 수 있다. 문제가 생기면 여기서 원인을 확인한다.

전체 시스템이 올라간 뒤의 아키텍처를 다시 한번 확인한다.

테스트 대시보드로 검증하기

단계 1 — 대시보드 접속

브라우저에서 http://localhost에 접속한다. 테스트 대시보드가 표시되면 Nginx 정적 파일 서빙이 정상이라는 뜻이다.

단계 2 — 헬스체크

4개의 "상태 확인" 버튼을 클릭한다. 모든 서비스가 "정상"으로 표시되면 라우팅이 잘 작동하는 것이다.

이 과정에서 일어나는 일을 흐름으로 보면 이렇다.

단계 3 — API 기능 테스트

"전체 사용자 조회" 버튼을 클릭한다. 결과 영역에 5명의 샘플 사용자 데이터가 표시된다. "사용자 생성 테스트" 버튼도 눌러보고, 다시 조회해서 6명이 되는지 확인한다.

Order와 Payment 서비스도 같은 방식으로 테스트한다.

단계 4 — Rate Limiting 검증

이 실습의 하이라이트다. "Rate Limit 테스트 (20회)" 버튼을 클릭하면, 20개의 요청이 동시에 발사된다.

초록 영역에서 6개 요청이 통과하고, 분홍 영역에서 14개가 429로 거부된다. 대시보드의 결과에 "Rate Limiting이 정상적으로 작동하고 있습니다!"가 표시되면 성공이다.

문제 해결

502 Bad Gateway

Gateway는 올라왔는데 백엔드 서비스가 아직 준비되지 않은 경우 발생한다. docker compose logs user-service로 Spring Boot 시작 로그를 확인하고, "Started UserServiceApplication" 메시지가 보일 때까지 기다린다.

서비스 상태가 "오류"

docker compose ps로 컨테이너 상태를 확인한다. healthcheck가 실패하면 unhealthy로 표시된다. docker compose logs <서비스명>으로 에러 로그를 확인한다.

Rate Limit 테스트에서 429가 하나도 안 나올 때

limit_req_zone의 rate가 너무 높거나, burst가 충분히 크면 모든 요청이 통과할 수 있다. api-gateway.conf의 설정을 확인한다. 또한 네트워크 지연으로 요청이 동시에 도착하지 않았을 수도 있다.

전체 재빌드

설정을 수정한 뒤 변경이 반영되지 않으면 캐시를 무시하고 재빌드한다.

docker compose down
docker compose build --no-cache
docker compose up -d

전체 시스템 종합 흐름

모든 것이 정상 동작할 때, 사용자 조회 요청의 전체 흐름을 처음부터 끝까지 따라간다.

이 하나의 다이어그램에 시리즈 전체의 핵심이 담겨 있다. 주황 영역은 Nginx의 라우팅과 Rate Limiting, 초록 영역은 프록시 전달과 응답 가공, 파란 영역은 Spring Boot의 비즈니스 로직 처리다.

시스템 종료

작업을 마치면 모든 컨테이너를 정리한다.

docker compose down

볼륨과 네트워크까지 완전히 제거하려면 -v 플래그를 추가한다.

docker compose down -v

자주 하는 실수