• 📦 1. 도입 배경

  • 1.1 기존 서비스 구조 개요
  • 1.2 기존 운영 및 배포 방식의 한계
  • 1.3 Docker 도입 필요성 요약
  • 1.4 도입 시 고려 포인트

• 🐳 2. Docker 도입의 필요성

  • 2.1 환경 불일치 문제 해결
  • 2.2 배포 자동화 수준 향상
  • 2.3 구성 요소별 의존성 및 자원 분리
  • 2.4 FastAPI 서버와의 통합 및 배포 전략 동일
  • 2.5 협업 생산성 향상
  • 2.6 향후 확장을 위한 기반 확보
  • 2.7 요약 표

• 🧭 3. 도커 아키텍처 설계

  • 3.1 전체 아키텍처 다이어그램
  • 3.2 배포 전략
  • 3.3 이미지 빌드 및 관리 전략

• 📋 4. Docker 기술 구성 명세서

  • 4.1 Next.js
  • 4.2 Spring Boot
  • 4.3 FastAPI
  • 4.4 로컬 테스트 용도 Docker-Compose

• 💰 5. 비용 계산 보고서

  • 5.1 개요
  • 5.2 리소스별 비용 및 구성
  • [5.3 총 예상 비용(#53-총-예상-비용)
  • 5.4 참고사항

현재 서비스는 AWS와 GCP에 걸쳐 다음과 같이 분산된 구성으로 운영되고 있다.

• AWS EC2 인스턴스 내에 주요 애플리케이션이 설치되어 실행
  • Next.js (프론트엔드): SSR 및 정적 페이지 렌더링
  • Spring Boot (백엔드 API 서버): 주요 비즈니스 로직 및 DB 연동
  • MySQL (RDB): 사용자 및 서비스 데이터 저장소
• GCP GCE FastAPI 서버: AI 모델 응답 처리
• 정적 리소스는 S3 Bucket에 저장되고 CloudFront를 통해 배포
• CI/CD GitHub Actions → S3 → AWS CodeDeploy로 연결

이 구조는 기능적으로는 분산된 서비스를 잘 운영하고 있으나, 배포 및 운영의 효율성과 신뢰성 측면에서 개선 여지가 크다.

이러한 문제들을 근본적으로 해결하기 위해, 서비스의 핵심 구성 요소를 Docker 기반으로 컨테이너화할 필요가 있다.

• 환경 구성 자동화: Dockerfile로 OS, 라이브러리, 런타임까지 명확히 정의
• CI/CD 연동 최적화: GitHub Actions에서 Docker 이미지 빌드 → ECR 푸시 → 배포까지 완전 자동화
• 배포 안정성 확보: 버전 명시된 이미지 태그 기반으로 재현 가능, 롤백 신속
• 운영 효율화: 각 구성 요소 컨테이너 격리 → 서비스간 충돌 방지, 자원 사용 최적화
• 클라우드 네이티브 전환 기반: 이후 ECS, EKS 등 오케스트레이션 환경으로 확장 가능

• 어떤 구성요소를 컨테이너화할 것인가?
  • 프론트(Next.js) / 백엔드(Spring Boot) / DB(MySQL) / AI 서버(FastAPI) 별로 나눠 설계
• 기존 CodeDeploy와의 연결성 유지 혹은 전환 여부
  • ECS or Fargate 활용 여부 검토
• 컨테이너 이미지 저장소는 ECR 또는 GitHub Container Registry 중 선택
• 기존 모니터링/로그 시스템(CloudWatch, S3)과 통합 유지 필요

• 개발자는 로컬(Mac, Windows)에서 Node.js, Java, Python 등 개별적으로 설치해 작업
• 운영 환경은 Amazon Linux 기반 → 라이브러리 버전 차이, OS 디렉토리 구조 차이 발생
• “내 로컬에서는 되는데 서버에서는 안 돼요” 문제 반복

• Dockerfile을 통해 실행 환경을 명시적으로 정의 (FROM, RUN, COPY, CMD)
• 개발, 테스트, 운영 전 구간에서 동일한 컨테이너 이미지로 실행
• 환경 의존성 제거 → 문제 발생 지점이 OS가 아닌 애플리케이션 레벨로 국한

예시: Next.js의 SSR 시 node 버전 차이로 인한 ReferenceError: fetch is not defined 오류 → 컨테이너로 버전 고정하여 해소

• GitHub Actions에서 zip으로 묶은 코드 → S3에 업로드 → CodeDeploy가 EC2에서 압축 해제
• .sh 스크립트와 appspec.yml에 로직을 직접 작성 → 변경에 매우 민감, 유지보수 어려움
• 롤백 시 수동 스크립트 실행 → 다운타임 위험 높음

• GitHub Actions에서 Docker 이미지 자동 빌드 및 태깅
• AWS ECR에 이미지 푸시 → ECS 혹은 EC2에서 docker run만으로 배포
• 버전 태그만 변경해도 과거 상태로 즉시 복구 가능 (v1.2.0 → v1.1.9)

정량 근거:

기존 배포 시간: 평균 15분 (압축, 업로드, 배포 대기 포함) -> Docker 도입 후: 평균 10분 (이미지 Pull + 실행)

• Next.js, Spring Boot, MySQL이 동일 EC2 인스턴스 내에 설치되어 공존
• 포트 충돌, 자원(메모리/CPU) 경쟁, 로그 혼합 저장 등 관리 복잡성 증가

• 각 서비스별 Docker 컨테이너로 실행 → 독립된 네트워크/자원/로그 경로 사용
• 장애 격리 및 문제 진단 용이 (e.g., docker logs, docker stats로 개별 추적 가능)
• 필요 시 개별 컨테이너만 재배포하거나 재시작 가능

예: Spring Boot만 재시작할 때 기존엔 전체 서버를 재부팅해야 했으나, 컨테이너 기반에서는 해당 컨테이너만 restart 하면 됨

• GCP에서 운영되는 FastAPI 서버는 AWS 서비스들과 별도 배포 관리
• 수동 배포 → 관리 일관성 부족

• GCP 역시 Docker 지원이 기본 → 동일한 Dockerfile 구조로 FastAPI 이미지 빌드 가능
• CI/CD 파이프라인을 동일한 GitHub Actions 워크플로우로 확장 가능
• 단일 이미지 버전으로 여러 클라우드 간 일관된 배포 전략 확보

• 개발자마다 Node.js, Java, Python 등 설치 및 설정이 상이
• 프로젝트 셋업 문서가 길고, 세팅 중 오류가 자주 발생

• docker-compose.yml 하나로 전체 개발 환경 구동 가능
• “로컬에서 실행 안 되는 문제” 거의 제거 → 개발에 집중 가능

• 마이크로서비스 아키텍처로의 확장
• ECS, Fargate, Kubernetes 기반 오토스케일링 고려
• Canary, Blue/Green Deployment, A/B 테스트 등 고급 배포 전략 도입

• 모든 오케스트레이션 플랫폼은 컨테이너 기반이 전제
• Docker 도입이 되어 있어야 ECS Task, Kubernetes Pod 등으로 이전 가능

본 아키텍처는 Blue/Green 배포 전략을 채택하여 다운타임 없는 안전한 배포를 목표로 한다. AWS CodeDeploy, Auto Scaling Group, ALB(Application Load Balancer)를 활용하여 두 개의 대상 그룹(Blue/Green) 간 전환을 자동화하였다.

[1] GitHub Actions에서 이미지 빌드 후 ECR에 푸시
 ↓
[2] CodeDeploy가 CD 트리거 수신 → 신규 ASG 인스턴스 기동 (Green Target Group)
 ↓
[3] Health Check 성공 시 → ALB 대상 그룹을 Blue → Green 으로 전환
 ↓
[4] 기존 Blue 그룹은 대기 상태로 유지 또는 종료
 ↓
[5] CloudWatch Alarm으로 성공/실패 감지 후 → Lambda → SNS → Discord 알림 발송

• latest 태그로 이미지 이중 생성 후 ECR에서 관리

• AWS ECR에 서비스 단위 저장소 및 태그 분리하여 관리
• ex: ecr.repo/fe-app, ecr.repo/be-app, ecr.repo/ai-app

• 운영용 이미지에 대해 cosign 서명 자동화 (main 브랜치 배포 시 서명 후 push)
• 서명 키는 OIDC 연동 + GitHub Actions 내부 Keyless Signing으로 관리

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

# 🔹 1단계: 빌드 스테이지
FROM gradle:8.5-jdk17-alpine AS build

WORKDIR /app

# 종속성 캐싱을 위해 먼저 복사
COPY build.gradle.kts settings.gradle.kts ./
COPY gradle ./gradle
RUN gradle build --no-daemon || return 0

# 전체 소스 복사 후 빌드
COPY . .
RUN gradle clean build --no-daemon

# 🔹 2단계: 런타임 이미지
FROM eclipse-temurin:17-jdk-alpine

WORKDIR /app
COPY --from=build /app/build/libs/*.jar app.jar

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Next.js, Spring Boot, FastAPI. MySQL을 포함하며, 각 서비스는 동일한 브릿지 네트워크에서 통신 가능하다.

# docker-compose.yml
version: "3.8"

services:
  nextjs:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - PORT=3000
    depends_on:
      - spring
      - fastapi

  spring:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=local
      - DB_HOST=db
      - DB_PORT=3306
      - DB_USERNAME=root
      - DB_PASSWORD=secret
    depends_on:
      - db

  fastapi:
    build:
      context: ./ai
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - ENV=local
      - MODEL_PATH=/app/model

  db:
    image: mysql:8.0
    container_name: mysql
    restart: always
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=secret
      - MYSQL_DATABASE=appdb
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

project-root/
├── docker-compose.yml
├── frontend/
│   └── Dockerfile (Next.js SSR)
├── backend/
│   └── Dockerfile (Spring Boot)
├── ai/
│   └── Dockerfile (FastAPI)

1. Docker Desktop 설치
2. Docker Compose 설치

sudo rm /usr/local/bin/docker-compose
sudo ln -s /Applications/Docker.app/Contents/Resources/cli-plugins/docker-compose /usr/local/bin/docker-compose
docker-compose --version

# 실행
docker-compose up -d 
# 중지
docker-compose down
# 컨테이너 상태 확인
docker-compose ps
# 로그 확인
docker-compose logs

• 본 문서는 하루 최대 접속자 150명을 기준으로 구성된 Docker 기반 마이크로서비스 아키텍처의 AWS 비용 산정 결과다.
• 모든 인프라는 EC2 인스턴스를 기반으로 컨테이너를 직접 배포하는 구조이며, DB와 Redis도 EC2에 직접 설치하여 운영 비용을 절감하였다.

• 약 $198.66 / 월
• 해당 비용은 On-Demand 기준, 하루 24시간 또는 일부 리소스는 6시간 가동을 기준으로 AWS 요금 계산기에서 산출하였음
• 실제 사용 시간, 요청 수, 트래픽 등에 따라 다소 차이가 발생할 수 있음

• CloudWatch 지표 수는 프리 티어 내에서 활용하고, Prometheus 기반 수집 및 Grafana 시각화로 외부 전송 비용 절약
• EC2 기반 DB, Redis는 자동 백업 및 점검 스크립트를 통해 운영 효율성 확보
• 모든 인프라 구성은 비용 최적화를 고려하여 EC2 인스턴스 기반으로 구성하였으며, 불필요한 매니지드 서비스 사용을 최소화함