🪵 3. 인프라 실습(5) : 실제 프로젝트에 적용해보기

Docker 기반의 CI/CD 파이프라인 구축하기

1. 프로젝트 구조

• VPC (10.0.0.0/16)

  Public Subnet은 외부와 연결되는 서비스, Private Subnet은 내부 리소스를 위한 환경으로 구성

• Public Subnet (10.0.1.0/24)

  사용자 요청을 처리하는 웹 서버와 웹 애플리케이션 서버가 위치

• Nginx

  정적 파일 제공 및 리버스 프록시로 동작하여 사용자 요청을 적절한 서비스로 라우팅

• NestJS

  /socket.io를 통해 WebSocket 요청을 처리하며, API 서버 역할 수행.

• Redis (Private Subnet, 10.0.2.0/24)

  클라우드 환경의 Redis를 활용하여 세션 관리 및 데이터 캐싱 처리

• Docker

  Nginx와 NestJS 애플리케이션 모두 Docker 컨테이너로 실행되며, 이미지는 Github Actions를 통해 빌드 및 Docker Hub에서 관리

• 배포 자동화

  CI/CD 파이프라인(Github Actions)을 통해 애플리케이션 빌드 및 배포 자동화

2. Docker 구성

Dockerfile.server

FROM node:20-alpine AS builder

RUN corepack enable && corepack prepare pnpm@9.12.3 --activate

WORKDIR /app

COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
COPY core/package.json ./core/
COPY server/package.json ./server/

RUN pnpm install --frozen-lockfile

COPY . .

RUN pnpm --filter @troublepainter/core build
RUN pnpm --filter server build

FROM node:20-alpine AS production
WORKDIR /app        

COPY --from=builder /app/pnpm-workspace.yaml ./
COPY --from=builder /app/server/package.json ./server/package.json
COPY --from=builder /app/server/dist ./server/dist
COPY --from=builder /app/core/package.json ./core/package.json
COPY --from=builder /app/core/dist ./core/dist

RUN corepack enable && corepack prepare pnpm@9.12.3 --activate && cd server && pnpm install --prod

WORKDIR /app/server

ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

CMD ["node", "dist/main.js"]

• 프로젝트 구조: core와 server가 포함된 모노레포 구조
• 빌드 프로세스: core 프로젝트 빌드 후 server 프로젝트 빌드
• 프로덕션 설정
  • 빌드된 core/server dist 파일만 복사
  • 프로덕션 의존성만 설치 (--prod 플래그)
  • server 디렉토리를 메인 작업공간으로 설정
• 환경 변수: NODE_ENV=production, PORT=3000 설정
• 포트: 3000번 포트 노출
• 실행 방식: Node.js로 server/dist/main.js 실행
• 최적화: 멀티 스테이지 빌드로 개발 의존성 제외

Dockerfile.nginx

FROM node:20-alpine AS builder

RUN corepack enable && corepack prepare pnpm@9.12.3 --activate

WORKDIR /app

COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
COPY core/package.json ./core/
COPY client/package.json ./client/

RUN pnpm install --frozen-lockfile

COPY . .

ARG VITE_API_URL
ARG VITE_SOCKET_URL

RUN echo "VITE_API_URL=$VITE_API_URL" > client/.env && echo "VITE_SOCKET_URL=$VITE_SOCKET_URL" >> client/.env && pnpm --filter @troublepainter/core build && pnpm --filter client build

FROM nginx:alpine

COPY nginx.conf /etc/nginx/templates/default.conf.template
COPY --from=builder /app/client/dist /usr/share/nginx/html

EXPOSE 80 443

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

• 프로젝트 구조: core와 client가 포함된 모노레포 구조
• 환경 변수: VITE_API_URL, VITE_SOCKET_URL을 빌드 시점에 주입
• 빌드 프로세스: core 프로젝트 빌드 후 client 프로젝트 빌드
• 배포 설정: nginx 웹서버로 빌드된 클라이언트 애플리케이션 서빙
• 포트: HTTP(80), HTTPS(443) 포트 노출
• 최적화: 멀티 스테이지 빌드로 최종 이미지 크기 최소화
• 실행 방식: nginx를 포그라운드에서 구동

3. Nginx 설정

nginx.conf

server {
    listen 80;
    server_name www.troublepainter.site;
    return 301 https://$server_name$request_uri;
}
server {
    listen 443 ssl;
    server_name www.troublepainter.site;

    ssl_certificate /etc/letsencrypt/live/www.troublepainter.site/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/www.troublepainter.site/privkey.pem;

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /api {
	    proxy_pass http://server:3000;
	    proxy_http_version 1.1;
	    proxy_set_header Host $host;
	    proxy_cache_bypass $http_upgrade;
		}

		location /socket.io {
	    proxy_pass http://server:3000;
	    proxy_http_version 1.1;
	    proxy_set_header Upgrade $http_upgrade;
	    proxy_set_header Connection "upgrade";
	    proxy_set_header Host $host;
		}
}

• HTTP(80) 설정
  • 모든 HTTP 요청을 HTTPS로 리다이렉트
  • 도메인: [www.troublepainter.site](http://www.troublepainter.site/)
• HTTPS(443) 설정
  • SSL 인증서 설정 (Let's Encrypt)
  • gzip 압축 활성화 (텍스트, CSS, JS 등)
  • 도메인: [www.troublepainter.site](http://www.troublepainter.site/)
• 라우팅 규칙
  1. / (프론트엔드)
     • 정적 파일 제공
     • SPA 라우팅 지원 (/index.html로 폴백)
  2. /api (HTTP API)
     • server:3000으로 프록시
     • HTTP 통신에 필요한 기본 헤더만 설정
  3. /socket.io (WebSocket)
     • server:3000으로 프록시
     • WebSocket 연결을 위한 upgrade 헤더 설정
• 모든 통신은 하나의 Node.js 서버(server:3000)에서 처리하며, 용도에 따라 경로만 구분되어 있음.

4. CI/CD 파이프라인

client-ci-cd.yml

name: Client CI/CD

on:
  push:
    branches: [develop]
    paths:
      - 'client/**'
      - 'core/**'
      - 'nginx.conf'
      - '.github/workflows/client-ci-cd.yml'
      - 'Dockerfile.nginx'

jobs:
  ci-cd:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Setup pnpm
        uses: pnpm/action-setup@v3
        with:
          version: '9'

      - name: Install Dependencies
        run: pnpm install --frozen-lockfile

      - name: Lint Client
        working-directory: ./client
        run: pnpm lint | true

      - name: Test Client
        working-directory: ./client
        run: pnpm test | true

      - name: Docker Setup
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: ./Dockerfile.nginx
          push: true
          tags: ${{ secrets.DOCKERHUB_USERNAME }}/troublepainter-nginx:latest
          build-args: |
            VITE_API_URL=${{secrets.VITE_API_URL}}
            VITE_SOCKET_URL=${{secrets.VITE_SOCKET_URL}}

      - name: Deploy to Server
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.SSH_HOST }}
          username: mira
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /home/mira/web30-stop-troublepainter
            export DOCKERHUB_USERNAME=${{ secrets.DOCKERHUB_USERNAME }}
            docker pull ${{ secrets.DOCKERHUB_USERNAME }}/troublepainter-nginx:latest
            docker compose up -d nginx

• Workflow 트리거
  • develop 브랜치 push 이벤트
  • 클라이언트, 코어, Nginx 관련 파일 변경 시에만 실행
• ci-cd
  • 초기 설정
    • Ubuntu 환경 설정
    • Node.js 20 설치
    • pnpm 9 설치
    • 의존성 설치
    • core 패키지 빌드
  • 코드 품질 검증
    • 클라이언트 린트 검사
    • 클라이언트 테스트 실행
    • (실패해도 파이프라인 계속 진행)
  • 도커 이미지 빌드/배포
    • Docker Buildx 설정
    • Docker Hub 로그인
    • Nginx 이미지 빌드 및 푸시
    • 환경변수 주입
  • 서버 배포
    • SSH로 서버 접속
    • 최신 이미지 pull
    • nginx 컨테이너 재시작

server-ci-cd.yml

name: Server CI/CD

on:
  push:
    branches: [develop]
    paths:
      - 'server/**'
      - 'core/**'
      - '.github/workflows/server-ci-cd.yml'
      - 'Dockerfile.server'

jobs:
  ci-cd:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Setup pnpm
        uses: pnpm/action-setup@v3
        with:
          version: '9'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build Core Package
        working-directory: ./core
        run: pnpm build

      - name: Create .env file
        working-directory: ./server
        run: |
          echo "REDIS_HOST=${{ secrets.REDIS_HOST }}" >> .env
          echo "REDIS_PORT=${{ secrets.REDIS_PORT }}" >> .env
          echo "CLOVA_API_KEY=${{ secrets.CLOVA_API_KEY }}" >> .env
          echo "CLOVA_GATEWAY_KEY=${{ secrets.CLOVA_GATEWAY_KEY }}" >> .env

      - name: Run tests
        run: pnpm --filter server test | true

      - name: Docker Setup
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: ./Dockerfile.server
          push: true
          tags: ${{ secrets.DOCKERHUB_USERNAME }}/troublepainter-server:latest
          build-args: |
            REDIS_HOST=${{ secrets.REDIS_HOST }}
            REDIS_PORT=${{ secrets.REDIS_PORT }}
            CLOVA_API_KEY=${{ secrets.CLOVA_API_KEY }}
            CLOVA_GATEWAY_KEY=${{ secrets.CLOVA_GATEWAY_KEY }}

      - name: Deploy to Server
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.SSH_HOST }}
          username: mira
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /home/mira/web30-stop-troublepainter
            export DOCKERHUB_USERNAME=${{ secrets.DOCKERHUB_USERNAME }}
            docker pull ${{ secrets.DOCKERHUB_USERNAME }}/troublepainter-server:latest
            docker compose up -d server

• Workflow 트리거
  • develop 브랜치 push 이벤트
  • 서버, 코어, Dockerfile 관련 파일 변경 시에만 실행
• ci-cd
  • 초기 설정
    • Ubuntu 환경 설정
    • Node.js 20 설치
    • pnpm 9 설치
    • 의존성 설치
    • core 패키지 빌드
  • 코드 품질 검증
    • 서버 환경변수(.env) 설정
    • 서버 테스트 실행
    • (실패해도 파이프라인 계속 진행)
  • 도커 이미지 빌드/배포
    • Docker Buildx 설정
    • Docker Hub 로그인
    • Server 이미지 빌드 및 푸시
    • 환경변수 주입 (Redis, Clova API)
  • 서버 배포
    • SSH로 서버 접속
    • 최신 이미지 pull
    • server 컨테이너 재시작

5. Docker Compose

docker-compose.yml

services:
  server:
    image: ${DOCKERHUB_USERNAME}/troublepainter-server:latest
    container_name: troublepainter_server
    environment:
      - NODE_ENV=production
      - REDIS_HOST=${REDIS_HOST}
      - REDIS_PORT=${REDIS_PORT}
      - CLOVA_API_KEY=${CLOVA_API_KEY}
      - CLOVA_GATEWAY_KEY=${CLOVA_GATEWAY_KEY}
    networks:
      - app_network
    restart: unless-stopped

  nginx:
    image: ${DOCKERHUB_USERNAME}/troublepainter-nginx:latest
    container_name: troublepainter_nginx
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - server
    networks:
      - app_network
    restart: unless-stopped

networks:
  app_network:
    name: app_network
    driver: bridge

• 여러 Docker 컨테이너를 정의하고 관리하기 위한 설정 파일
• 서비스 구성
  • Server 서비스 (Node.js 애플리케이션)
  • Nginx 서비스 (웹서버/프록시)
• API 서비스 설정
  • 컨테이너명: troublepainter_server
  • 환경변수: NODE_ENV, Redis 연결 정보, Clova API 인증키
  • 자동 재시작 정책 적용
  • app_network에 연결
• Nginx 서비스 설정
  • 컨테이너명: troublepainter_nginx
  • SSL 인증서 볼륨 마운트 (/etc/letsencrypt)
  • 80/443 포트 노출
  • API 서비스에 의존성 설정
  • app_network에 연결
• 네트워크 설정
  • 네트워크명: app_network
  • 타입: bridge 네트워크
    • 같은 Docker 호스트 내에서 실행되는 컨테이너들이 서로 통신할 수 있게 해주는 가상의 네트워크

현재 구조의 단점과 향후 계획

1. Nginx의 역할 중복

• Nginx가 정적 파일 호스팅과 리버스 프록시 두 가지 역할 수행
• 서버 리소스 사용 증가

2. 클라이언트 코드 변경 시 Nginx 이미지 빌드

• 클라이언트 코드 변경시마다 Nginx 이미지 재빌드 필요
• 배포 시간 증가, 리소스 낭비
• Nginx 설정 변경만 필요할 때도 전체 빌드 필요

3. 하나의 프로세스에서 모든 작업 처리

• HTTP API와 Socket.IO가 하나의 프로세스에서 동작
• 트래픽 증가 시 개별 스케일링 불가
• 한 기능의 장애가 전체 서비스에 영향

---

1. Nginx의 역할 중복 문제 해결

• 정적 파일 분리
  • 정적 파일은 Nginx가 아닌 AWS S3와 같은 오브젝트 스토리지에 업로드하고, CDN(Content Delivery Network)을 활용해 전 세계적으로 빠르게 배포
  • 이를 통해 Nginx가 리버스 프록시 역할에만 집중할 수 있도록 개선
• HTTPS 지원 강화
  • Cloudflare 같은 CDN 서비스에서 HTTPS를 제공하도록 설정해 보안 강화
  • 내부 네트워크에서는 HTTP 통신으로 전환하여 리소스 최적화

2. 클라이언트 코드 변경 시 Nginx 이미지 재빌드 문제 해결

• Nginx 이미지와 정적 파일의 분리
  • Nginx 이미지는 정적 파일 없이 설정 파일만 포함
  • 클라이언트 빌드 결과물은 Nginx 컨테이너의 외부 볼륨으로 연결하여 이미지 재빌드 없이 동적으로 제공
• 배포 자동화
  • CI/CD 파이프라인에서 정적 파일 빌드 후 스토리지로 업로드하거나 Nginx 컨테이너의 볼륨에 바로 복사

3. 모든 작업을 하나의 프로세스에서 처리하는 문제 해결

• 서비스 분리
  • HTTP API 서버와 WebSocket 서버(Socket.IO)를 별도의 프로세스 또는 컨테이너로 분리
  • 각 프로세스는 독립적으로 배포 및 스케일링 가능
• 로드 밸런싱
  • API 서버와 WebSocket 서버 앞단에 로드 밸런서를 두어 트래픽을 균등 분배
  • Nginx나 HAProxy, AWS ELB와 같은 로드 밸런서 사용
• 오토 스케일링