애플리케이션 Docker Image 구성

서비스별 Dockerfile 구조

서비스	런타임	빌드 전략	포트
Backend
Frontend	Next.js	멀티스테이지 (node 빌드 → node 런타임, standalone node server.js)	3000
AI	FastAPI	단일 스테이지	8000

• 더미 앱은 헬스체크 엔드포인트만 제공하고 비즈니스 로직은 없음
  • 추후 코드가 완성되면 코드만 넣어 Docker Image로 빌드할 수 있어야 함
• Frontend, AI는 tobby가, Backend는 janna가 작성한다. 이 문서의 Dockerfile은 Frontend, AI다.

최적화 범위 결정

작성 전 계획한 최적화 범위는 다음 4단계였다.

1. COPY/RUN만으로 기본 빌드
2. 이미지 크기 축소 — 멀티스테이지 빌드, Next.js standalone 모드
3. 빌드 속도 개선 — 이미지 레이어 배치, BuildKit cache mount
4. 각 단계마다 지표를 두고 개선 폭 측정

이 범위는 v1의 배포 목표와 맞지 않았다. v1의 기준은 적은 비용과 빠른 배포인데, 위 계획은 프로덕션 수준의 세밀한 최적화에 해당한다고 판단했다. 비용에 직접 영향을 주는 항목과 지금 급하지 않은 항목을 구분하지 않고 한 번에 처리하려 한 것이 문제였다.

그래서 비용에 가장 크게 영향을 주는 이미지 크기만 v1의 최적화 대상으로 좁혔다.

항목	v1 적용	판단 근거
이미지 크기 (멀티스테이지, standalone)	적용	GHCR 전송량과 EC2 루트 볼륨 사용량에 직접 영향. 단일 인스턴스에 현재 이미지와 롤백용 이전 이미지가 함께 남는다
의존성 레이어 분리 (의존성 파일 먼저 COPY)	적용	두 줄로 끝나고 PR마다 도는 CI 빌드 시간에 바로 반영된다
BuildKit cache mount	제외	빌드 속도 항목. v1 규모에서 CI 시간이 아직 문제가 아니다
non root 유저 실행	제외	보안 항목. v1은 부트캠프 내부 전용 서비스이며, 우선순위를 이미지 크기에 두었다

Dockerfile 공통 요구사항

• linux/arm64 (AWS EC2 t4g.medium)
  • 팀원 모두 Mac(arm64)를 사용하므로 로컬, 운영 환경 모두 arm64만 필요함
  • Github Actions 러너
    • Github Actions Runner는 기본적으로 x86(amd64)
    • ARM용 이미지를 빌드하기 위해서는 ARM 러너를 따로 사용하거나 QEMU buildx로 크로스 빌드 필요(네이티브 빌드에 비해 느림)
    • 따라서 Github Actions에서 runs on으로 네이티브 arm64 러너를 사용해 빌드한다
• 실제 코드가 나중에 들어와도 변경 없이 빌드할 수 있어야 함
• 환경 변수는 런타임에 주입
  • NEXT.js의 NEXT_PUBLIC_ 제외
• HEALTHCHECK은 docker compose에서 관리해, 어느 쪽이 롤백의 트리거가 되었는지 추적하기 쉽도록 한다.

프론트엔드 Dockerfile

Next.js는 요청마다 서버에서 렌더링하는 Node 프로세스이므로(설계 문서의 FE → BE SSR 호출) 정적 파일로 내보낼 수 없고, 컨테이너로 단독 실행해야 한다. 따라서 output: 'standalone'을 전제로 한다.

기본 구성 (비교용)

FROM node:22

WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

EXPOSE 3000
CMD ["npm", "start"]

• 이미지 크기 2.61 GB
• 단일 스테이지이므로 빌드 도구, devDependencies, 소스가 모두 최종 이미지에 남는다

채택 구성 — 멀티스테이지 + standalone

FROM node:24.21.0-alpine AS builder

WORKDIR /app

# 의존성 파일만 먼저 복사하여 설치
COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM node:24.21.0-alpine AS runner

WORKDIR /app

ENV HOSTNAME=0.0.0.0

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
CMD ["node", "server.js"]

• 이미지 크기 284.92 MB — 기본 구성의 약 1/9
• output: 'standalone'은 운영에 실제로 필요한 파일만 골라주고, 멀티스테이지는 그것만 최종 이미지에 옮긴다.
• .next/standalone에는 .next/static과 public이 포함되지 않아 별도로 COPY한다. .next/static이 빠지면 페이지는 뜨지만 JS/CSS가 404가 된다
• ENV HOSTNAME=0.0.0.0 — standalone server.js는 기본적으로 localhost에 바인딩한다. 0.0.0.0으로 열지 않으면 Nginx 컨테이너에서 접근할 수 없다
• npm install 대신 npm ci — lock 파일 그대로 설치
• 앱이 레포 루트가 아닌 하위 디렉터리(ktb_agile_frontend/)에 있으므로 Dockerfile을 하위 디렉토리에 두었다.
• Frontend Dockerfile PR

AI Dockerfile

FROM python:3.13.13-slim

WORKDIR /app

COPY . .

RUN pip install --no-cache-dir -r requirements.txt

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

• 이미지 크기 268.32 MB
• Python은 컴파일 산출물이 없어서 프론트엔드와 달리 단일 스테이지로 두어도 크기가 충분히 작다
• --no-cache-dir — pip이 내려받은 wheel을 ~/.cache/pip에 저장하는데 이것이 레이어에 남으므로 애초에 만들지 않도록 설정한다
• --host 0.0.0.0 — uvicorn의 기본 바인딩은 127.0.0.1이며, 그대로 두면 컨테이너 자신만 접속할 수 있어 백엔드 컨테이너의 요청이 닿지 않는다
• AI 서버는 백엔드만 호출하므로 compose에서 ports:를 공개하지 않고 내부 네트워크로만 둔다
• AI Dockerfile PR

실제 코드 반영 시 확인할 조건

Dockerfile이 각 레포의 구조에 의존하는 지점으로, 바뀌면 Dockerfile을 함께 수정해야 한다.

서비스	조건
Frontend	next.config에 output: 'standalone'
Frontend	package.json + package-lock.json, npm run build 스크립트
Frontend	public/ 디렉터리 존재
Frontend	클라이언트에서 쓰는 API 주소는 상대 경로(/api). NEXT_PUBLIC_*는 빌드 시점에 번들에 인라인되므로 런타임 주입으로 바꿀 수 없다. 절대 URL이 필요해지면 ARG 추가와 dev/prod 이미지 분리가 필요하다
AI	requirements.txt가 컨텍스트 루트에 있을 것
AI	app/main.py의 FastAPI 인스턴스명이 app일 것