4단계: Docker 컨테이너화 배포

컨테이너 구조 다이어그램

Docker 도입 후 서비스는 다음과 같은 구조로 구성됩니다.
각 환경은 동일한 구성 요소로 이루어져 있으며, Dev 환경은 테스트 및 검증용, Prod 환경은 실제 서비스 사용자 대상입니다.

Docker 도입 결정 및 범위

1. 도입 배경 (왜 Docker를 도입했는가?)

우리 서비스는 단일 EC2 인스턴스에서 React(프론트엔드), Spring Boot(백엔드), MySQL(DB)로 구성되어 있으며, 깃허브에서 git clone으로 EC2로 받아오는 방식으로 수동 배포를 진행해 왔습니다. 이후 GitHub Actions 기반의 CI/CD 파이프라인을 도입하며 자동화 수준을 높였지만, 여전히 각 서비스가 동일한 EC2 OS 내에서 실행됨에 따라 환경 충돌, 확장성 부족같은 문제가 발생했습니다.

따라서, Docker를 도입하기로 결정한 이유는 아래와 같습니다:

---

2. 도입 목적

이유	부가 설명
환경 불일치 해결	- 개발자마다 언어 버전 또는 OS 환경이 달라 생기는 문제, 의존성 충돌 등 발생 - Docker 이미지로 통일된 실행 환경을 제공하여 로컬에선 되는데, 서버에선 안 되는 문제 해소
서비스 간 간섭 방지	- 모든 구성요소가 동일한 OS 내에서 실행될 경우 의존성 충돌, 포트 충돌 발생 위험 - 컨테이너로 격리하여 충돌 없이 독립적 실행 가능
확장성 부족 해소	- 현재는 단일 인스턴스에 서비스가 직접 올라가 있어 수평 확장 어려움 - Docker 기반으로 서비스 단위 컨테이너화하여 향후 분산 운영 구조로 전환을 위한 발판 마련
복구 및 이전 비용 절감	- Docker 이미지 재배포만으로 인프라 변경 시에도 동일 서비스 재현 가능
버전 관리 용이	- Dockerfile 기반으로 각 버전을 명확하게 태깅 가능 - 태깅으로 이전 이미지로 쉽게 롤백 가능 (release-v2.0.0 -> release-v1.0.0)
Blue-Green 배포 구조 전환 용이	- 컨테이너 단위로 포트를 바꿔가며 트래픽 전환 가능 - 실행 중인 인스턴스는 그대로 두고 컨테이너만 교체하여 서비스 전환 간소화
Terraform 연계 가능성 확보	- 인프라는 Terraform으로 고정한 채, Docker로 서비스만 유연하게 전환 가능 - IaC(Terraform) + 컨테이너 배포 전략의 통합 관리 기반 마련

---

3. 도입 범위

Docker를 도입하여 서비스 구성 요소를 다음과 같이 분리된 컨테이너로 관리하고자 합니다:

• React 프론트엔드 → Nginx 기반 정적 파일 서빙 컨테이너

• Spring Boot 백엔드 → JDK 기반 애플리케이션 컨테이너

• FastAPI(AI) → Python 기반 애플리케이션 컨테이너

• MySQL 데이터베이스 → MYSQL 컨테이너로 사용

---

4. 도입 시 예상되는 변화

• 배포 효율성 향상: 이미지 빌드 및 푸시 후 간단한 pull & run으로 배포 자동화

• 테스트 환경 통일: 동일한 Docker 이미지로 QA 테스트 및 로컬 테스트 가능

• 버전 관리 명확화: 각 서비스별 Dockerfile 및 이미지 태그를 통해 릴리즈 관리 용이

• 장기적으로 오케스트레이션 가능성 확보: Docker Compose 및 추후 Kubernetes와의 연계 시 용이

---

컨테이너 배포 전략

1. Docker 도입 전략 설명서

빌드 방식

서비스별로 독립된 Dockerfile을 작성하여 GitHub Actions에서 이미지 빌드 자동화

• React: 정적 파일 빌드 후 Nginx에 포함

• Spring Boot: JAR 파일을 포함한 OpenJDK 기반 이미지

• FastAPI: Python 환경 기반으로 requirements.txt 설치 후 Uvicorn 실행 이미지

---

이미지 태깅 전략

• latest
  • 개발 환경에서 유용
  • 항상 최신 버전을 가리킴
  • 가장 최근에 빌드된 이미지
• v1.0.0
  • 명시적 버전 관리
  • 프로덕션 환경에서 유용

최종 선택: 운영 환경은 v1.0.0 태그 기반 배포, 개발 환경은 latest 활용

---

Docker 도입 후 CI/CD 순서

1. GitHub Actions에서 코드 푸시 감지

   • 브랜치 푸시 또는 PR 병합 발생 시 워크플로우 트리거

2. 코드 빌드 (Dockerfile)

   • Spring Boot는 ./gradlew build를 수행하여 .jar 생성
   • React는 npm run build를 수행하여 build 폴더 생성
   • FAST API는 requirements.txt를 설치

3. Docker 이미지 빌드

   • docker build -t my-app:release-v1.0.0 .

     -> 서비스별로 이미지 각각 빌드 (프론트, 백엔드등)

4. 이미지 레지스트리에 푸시(ECR)

   • docker push my-app:release-v1.0.0

     → DockerHub에 푸시

5. AWS CodeDeploy를 통해 EC2에 배포

   • CodeDeploy가 이미지가 푸시된 것을 감지하고 EC2 인스턴스에 배포 수행
   • AppSpec 파일(appspec.yml)을 통해 컨테이너 pull, stop, run 단계 자동화

---

이미지 저장소

• ECR 사용

---

컨테이너 간 연동 방식

• 모든 컨테이너는 동일한 브릿지 네트워크 (app-network) 상에 존재.
• 컨테이너 간 통신은 서비스 이름(DNS 이름처럼 작동)으로 가능하며, 별도 IP 설정 없이 도커 내부 네트워크로 접근.
• 내부 포트는 컨테이너 간 통신용이며, 외부 포트는 보안 그룹 또는 프록시(Nginx 등)로 제한.
• 예를 들어, React 앱에서 http://spring:8080으로 Spring Boot에 접근.

예시: docker-compose.yml 내 컨테이너 연동

version: '3.8'

services:
  react:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    networks:
      - app-network
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=development
    depends_on:
      - spring
      - fastapi

  spring:
    build:
      context: ./backend
      dockerfile: Dockerfile
    networks:
      - app-network
    ports:
      - "8001:8001"
    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
    networks:
      - app-network
    ports:
      - "8000:8000"

networks:
  app-network:

---

호스트 머신 자원 할당 전략

현 상황

현재 EC2 인스턴스는 t3.medium (2 vCPU, 4GB RAM) 스펙으로, React + Spring Boot을 단일 머신에서 React와 Spring Boot를 컨테이너로 운영할 예정. Docker는 기본적으로 컨테이너에 리소스 제한을 두지 않기 때문에, 각 컨테이너가 과도하게 자원을 점유하지 않도록 명시적으로 CPU/메모리 제한을 설정.

호스트 머신 자원 할당표

서비스	특성	예상 리소스	제한 예시
React (Nginx)	정적 파일 서빙, 경량	CPU: 매우 낮음RAM: 낮음	cpus: 0.4, memory: 256M
Spring Boot	메인 API 서버	CPU: 중간~높음RAM: 높음	cpus: 1.6, memory: 3072M

※ 모든 리소스를 합쳐도 2 vCPU, 4GB 이내로 구성해야 함

총합: 2.0 vCPU, 3328MB RAM 사용 (여유분 768MB 확보)

---

개발 환경에서의 Docker Compose 구성

version: "3.8"
services:
  frontend:
    build: ./frontend
    ports:
      - "8080:80"
    volumes:
      - ./frontend:/app
    environment:
      - NODE_ENV=development

  backend:
    build: ./backend
    ports:
      - "8001:8001"
    environment:
      - SPRING_PROFILES_ACTIVE=dev

  ai:
    build: ./ai
    ports:
      - "8000:8000"

🎯 운영 환경에서는

• GitHub Actions → Docker 이미지 빌드 → ECR 푸시

• EC2에서 docker pull + docker run으로 운영

• 리소스 제한 (--memory, --cpus) 설정 필수

• .env 대신 운영 변수는 EC2 환경 변수, AWS Secrets Manager, .tfvars 등으로 분리

---

공통 구성 요소 (Dev / Prod)

구성 요소	설명
VPC/Subnet	퍼블릭 및 프라이빗 서브넷으로 분리 구성 (AZ 분산)
EC2 (Auto Scaling Group)	프론트엔드, 백엔드, FastAPI 앱이 Docker 컨테이너 형태로 배포
MySQL (AWS RDS)	컨테이너화 없이 AWS의 RDS를 사용해 프라이빗 서브넷에서 접근
Docker + GitHub Actions	빌드 및 ECR 이미지 푸시는 GitHub Actions를 통해 수행
AWS CodeDeploy	배포는 CodeDeploy가 담당하며, EC2 인스턴스에서 이미지 pull & 실행
OpenVPN	외부 접근 시 보안 연결 용도
ALB + Route53	ALB를 통해 트래픽 분산, Route53으로 사용자 도메인 연결 처리

---

환경별 차이

환경 구분	목적	접근 대상	특징
Dev	개발 및 테스트	개발자	실제 운영과 동일한 구조에서 테스트 수행
Prod	실 서비스 운영	최종 사용자	실 트래픽 대응, 고가용성 구성 및 보안 강화

---

서비스 내 컨테이너 역할

컨테이너	기능
React (Nginx)	정적 파일 서빙
Spring Boot	사용자 인증, 비즈니스 로직
FastAPI	AI 모델 추론 및 API 처리

---

외부 연동

• Docker 이미지 저장소: AWS ECR
• CI: GitHub Actions
• CD: AWS CodeDeploy
• AI 서비스: FastAPI는 퍼블릭 인스턴스에서 직접 호스팅

이 구조는 환경 일관성, 확장성, 보안성을 고려하여 설계되었으며, CI/CD 자동화와 클라우드 자원 활용을 통해 서비스 배포 속도와 안정성을 확보했습니다.

---

2. Docker 기반 서비스 기술 명세

1. React (Static SPA)

• 베이스 이미지: node:18-alpine, nginx:stable-alpine
• 컨테이너 수: 8개 (Prod용, Dev용 4개, AZ 당 2개)
• 역할: React 앱을 빌드하여 Nginx로 정적 파일 서빙
• 포트: Host 3000 → Container 80
• 환경변수: REACT_APP_API_URL=http://localhost:8080 등

---

Dockerfile (frontend/Dockerfile)

FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

FROM nginx:stable-alpine

COPY nginx.conf /etc/nginx/nginx.conf

COPY --from=builder /app/build /usr/share/nginx/html

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

---

2. Spring Boot

• 베이스 이미지: openjdk:17, gradle:8.5-jdk17-alpine
• 컨테이너 수: 8개 (Prod용, Dev용 4개, AZ 당 2개)
• 역할: 사용자 인증, 데이터 처리 등 비즈니스 로직 수행
• 포트: Host 8080 → Container 8080
• 환경변수 예시: SPRING_PROFILES_ACTIVE=prod, DB_HOST=root 등

---

Dockerfile (backend/Dockerfile)

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

FROM eclipse-temurin:17-jdk-alpine

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

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

---

3. FastAPI (AI 서비스)

• 베이스 이미지: python:3.13-slim
• 컨테이너 수: 4개 (GCP Compute Engine당 2개씩)
• 역할: 모델 추론 및 AI API 제공
• 포트: Host 8000 → Container 8000
• 환경변수 예시: MODEL_PATH=/app/model, ENV=prod 등

---

Dockerfile (ai/Dockerfile)

FROM python:3.13-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"]

---

참고자료

아키텍쳐 개선