Next.js 프로젝트 배포 보고서

이 보고서는 Next.js 애플리케이션을 AWS EC2 t3.small 인스턴스에 Docker Compose를 이용해 배포하는 전 과정을 단계별로 설명합니다. 프로젝트는 Next.js의 App Router와 최신 기능들을 사용하고 있으며, Docker의 멀티 스테이지 빌드를 통해 최종 이미지 크기를 최소화할 예정입니다.

1. 개요 • 프로젝트: Next.js 기반 웹 애플리케이션 • 배포 환경: AWS EC2 t3.small • 배포 방식: Docker Compose를 사용한 컨테이너 기반 배포 • 배포 옵션: 멀티 스테이지 빌드를 활용하여 Standalone 출력(최종 이미지 약 110MB)

2. 사전 준비 사항

2.1 AWS EC2 인스턴스 준비 • 인스턴스 유형: t3.small • 보안 그룹 설정: • HTTP(포트 80) 또는 커스텀 포트(예: 3000)를 열어 외부에서 접근할 수 있도록 설정합니다. • Docker 내부 통신을 위해 추가 포트가 필요한 경우도 고려합니다.

2.2 서버 환경 설정

1. SSH 접속: 로컬에서 EC2 인스턴스로 SSH 접속합니다.

2. Docker 및 Docker Compose 설치: • Docker 설치 가이드(예: 공식 Docker 설치 문서)를 참고하여 Docker를 설치합니다. • Docker Compose가 설치되어 있지 않다면 Docker Compose 설치를 진행합니다.

3. 프로젝트 소스 준비: • Git 저장소에서 프로젝트를 클론하거나, 파일을 EC2 인스턴스로 복사합니다. • 프로젝트 루트에는 이미 package.json, next.config.ts 등 Next.js 설정 파일과 위에서 제공된 디렉터리 구조가 존재해야 합니다.

4. Docker 환경 구성

3.1 Dockerfile 작성

멀티 스테이지 빌드를 사용하여 다음과 같이 Dockerfile을 작성합니다. (예시는 Node.js 16-alpine 이미지를 사용하지만, 필요에 따라 버전을 조정하세요.)

1단계: 빌드 단계

FROM node:16-alpine AS builder WORKDIR /app

캐시 활용을 위해 의존성 파일 먼저 복사

COPY package.json package-lock.json ./ RUN npm ci

전체 소스 복사 후 빌드 실행

COPY . . RUN npm run build

2단계: 런타임 단계 (Standalone 출력)

FROM node:16-alpine AS runner WORKDIR /app

환경 변수 설정 (production 모드)

ENV NODE_ENV=production

빌드 산출물 복사

COPY --from=builder /app/.next ./.next COPY --from=builder /app/public ./public COPY --from=builder /app/package.json ./

프로덕션 의존성만 설치

RUN npm ci --only=production

포트 설정 (Next.js는 기본적으로 3000 포트 사용)

EXPOSE 3000

애플리케이션 시작

CMD ["npm", "start"]

참고:
	•	npm run build 스크립트는 next build를 호출하여 프로덕션 최적화된 애플리케이션을 생성합니다.
•	Docker 이미지에 필요한 파일(예: .next, public)만 복사하여 이미지 용량을 최소화합니다.

3.2 Docker Compose 파일 작성

프로덕션용 Docker Compose 파일(compose.prod.yaml) 예시는 다음과 같습니다.

version: "3.8"

services: web: build: context: . dockerfile: Dockerfile ports:

• "3000:3000" restart: always environment:

필요한 환경 변수 (예: NEXT_PUBLIC_ 접두어로 노출할 값)

NODE_ENV: production

추가 팁:
	•	개발 환경과 분리하기 위해 compose.dev.yaml 파일을 별도로 둘 수 있으며, 프로덕션은 멀티 스테이지 빌드와 Standalone 출력 사용을 권장합니다.
•	필요에 따라 볼륨 마운트, 환경 변수 파일(.env) 설정 등을 추가할 수 있습니다.

4. 배포 과정

4.1 EC2 인스턴스에서 프로젝트 설정

1. SSH 접속 후 프로젝트 디렉터리 생성 및 이동

mkdir ~/my-nextjs-app cd ~/my-nextjs-app

Git 저장소 클론 (또는 파일 업로드)

git clone .

2.	필수 파일 확인:
•	package.json에 "build"와 "start" 스크립트가 존재하는지 확인합니다.
•	위에서 작성한 Dockerfile과 compose.prod.yaml 파일을 프로젝트 루트에 위치시킵니다.

4.2 Docker 네트워크 생성 (옵션)

만약 여러 컨테이너가 통신해야 하거나 네트워크를 분리하고 싶다면 다음 명령어로 네트워크를 생성할 수 있습니다.

docker network create my_network

Compose 파일 내에서 별도 네트워크를 지정할 수도 있지만, 단일 컨테이너인 경우 생략해도 무방합니다.

4.3 이미지 빌드 및 컨테이너 실행

1. 프로덕션 이미지 빌드

docker compose -f compose.prod.yaml build

2.	컨테이너 실행 (백그라운드 모드)

docker compose -f compose.prod.yaml up -d

3.	실행 확인
•	컨테이너 로그를 확인하여 애플리케이션이 정상적으로 시작되었는지 확인합니다.

docker compose -f compose.prod.yaml logs -f

•	브라우저에서 http://<EC2-퍼블릭-IP>:3000으로 접속하여 애플리케이션이 정상 작동하는지 확인합니다.

5. 추가 설정 및 고려 사항

5.1 환경 변수 관리 • 빌드 타임과 런타임 환경 변수 모두 지원되므로, 민감하지 않은 값은 NEXT_PUBLIC_ 접두어를 붙여 브라우저에 노출하고, 민감한 값은 서버에서만 사용하도록 구성합니다. • 필요하다면 Docker Compose의 environment 옵션이나 .env 파일을 사용해 설정합니다.

5.2 로그 및 모니터링 • AWS CloudWatch Logs 또는 다른 로그 수집 도구를 연동하여 컨테이너 로그를 모니터링합니다. • 프로덕션 환경에서는 컨테이너 자동 재시작(restart: always) 옵션을 활용하여 장애 시 자동 복구하도록 합니다.

5.3 보안 그룹 및 포트 설정 • EC2 보안 그룹에서 3000 포트(또는 애플리케이션에서 사용하는 포트)가 외부에서 접근 가능하도록 설정합니다. • 필요에 따라 리버스 프록시(Nginx 등)를 사용하여 SSL 종료 및 도메인 라우팅을 구성할 수 있습니다.

5.4 업데이트 및 배포 전략 • 새 버전을 배포할 때는 Docker 이미지를 다시 빌드한 후, 기존 컨테이너를 교체합니다. • Blue/Green 배포 또는 롤링 업데이트 전략을 도입하여 다운타임 없이 업데이트할 수 있도록 고려합니다.

6. 결론

본 보고서에서는 AWS EC2 t3.small 인스턴스에 Next.js 프로젝트를 Docker Compose를 통해 배포하는 전체 과정을 설명했습니다. 주요 단계는 다음과 같습니다.

1. 환경 설정: EC2 인스턴스에 Docker 및 Docker Compose 설치
2. Dockerfile 작성: 멀티 스테이지 빌드를 이용한 프로덕션 이미지 생성
3. Compose 파일 구성: compose.prod.yaml 파일로 컨테이너 설정
4. 빌드 및 배포: 이미지 빌드 후 Docker Compose로 실행 및 테스트
5. 추가 구성: 환경 변수, 보안, 모니터링, 업데이트 전략 등 추가 고려 사항 반영

이제 위 과정을 따라 진행하면 AWS EC2 인스턴스에서 안정적이고 최적화된 Next.js 애플리케이션 배포가 가능합니다.

필요에 따라 보고서에 관련 명령어, 설정 파일, 테스트 결과 스크린샷 등을 추가하여 최종 보고서를 완성하면 좋습니다.