배경

juniverse-dev는 모노레포에서 front, admin, back을 각각 Docker 이미지로 배포하고 있었다.

기존에는 Next.js 앱(front, admin)을 빌드한 뒤 런타임 컨테이너에서도 pnpm start 방식으로 실행했는데,

GitHub Actions 배포 단계에서 장애가 발생했다.

Lightsail에서 이미지를 docker compose pull 받을 때 이미지가 약 400MB ~ 500MB 수준으로 커지면서, 이미지를 pull 받는데 1시간 이상이 소요되며 타임아웃이 발생헀던 것이다.

추가로 서버의 용량을 확보하기위해 배포할때마다 docker system prune -f를 수행하고 있었기 때문에 재사용 가능한 레이어가 줄어들어 pull 비용이 더 커지고 타임아웃 가능성이 높아졌다.

요약하자면

런타임 이미지에 불필요한 파일이 많이 포함될 수 있음
빌드 컨텍스트가 커져 Docker 빌드 시간이 증가
모노레포 환경에서 파일 추적 범위가 명확하지 않으면 런타임 누락 가능성 존재

이번 최적화 작업의 목표는 다음 3가지였다.

Next.js 런타임 산출물 최소화
Docker 이미지 경량화
배포 시 pull 타임아웃 리스크 감소

1. Next.js `output: 'standalone'` 적용

모노레포 안정성을 위해 outputFileTracingRoot를 추가했다.

`apps/front/next.config.ts`

import type { NextConfig } from 'next';
import path from 'path';

const nextConfig: NextConfig = {
  output: 'standalone',
  outputFileTracingRoot: path.join(__dirname, '../../'),
};

export default nextConfig;

apps/admin/next.config.ts도 동일하게 적용했다.

왜 `outputFileTracingRoot`가 필요한가

모노레포에서는 앱이 루트/공용 라이브러리(libs/*)를 참조한다.

standalone 빌드 시 Next가 런타임에 필요한 파일을 추적하는데, tracing root가 좁으면 일부 파일이 누락될 수 있다.

2. Dockerfile 멀티 스테이지 + standalone 런타임 구조로 전환

핵심은 빌더에서만 의존성 설치/빌드하고, 런너에는 standalone 산출물만 복사하는 것이다.

기존(개념)

단일 스테이지
pnpm install + pnpm build
컨테이너 실행 시 pnpm --filter <app> start

변경 후(개념)

builder 스테이지: 설치 + 빌드
runner 스테이지: .next/standalone, .next/static, public만 복사
실행: node apps/<app>/server.js

`docker/front.Dockerfile`

FROM node:24-alpine AS builder

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

WORKDIR /app

COPY pnpm-workspace.yaml ./
COPY package.json ./
COPY pnpm-lock.yaml ./
COPY .pnpmrc ./
COPY tsconfig.json ./

COPY apps ./apps
COPY libs ./libs

RUN pnpm install --frozen-lockfile
RUN pnpm --filter apis build
RUN pnpm --filter front build

FROM node:24-alpine AS runner

WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000

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

EXPOSE 3000
CMD ["node", "apps/front/server.js"]

docker/admin.Dockerfile도 같은 패턴으로 적용했다.

3. `.dockerignore` 정리

멀티 스테이지로 바꿔도 빌드 컨텍스트가 크면 빌드가 느리다.

그래서 루트 기준 패턴뿐 아니라 하위 경로까지 확실히 제외하도록 보강했다.

핵심 추가 항목

*/.next, */dist, */build, */coverage
.pnpm-store, */.turbo
*/.env, */.env.local, */.env.*.local
.github

이렇게 하면 Docker daemon으로 전송되는 컨텍스트 자체가 줄어든다.

Docker Compose는?
이번 변경에서는 docker-compose.yml 수정이 필수는 아니었다.
compose는 이미지 태그와 포트를 참조할 뿐
실행 방식 변경(pnpm start -> node .../server.js)은 Dockerfile 내부에서 해결됨
즉, 앱 이미지 내부 실행 구조가 바뀌어도 compose 레벨에서 반드시 손댈 필요는 없었다.

4. `docker system prune -f` 영향

배포 후 정리를 위해 prune을 쓰는 건 흔한 패턴이지만, 운영 환경에서는 트레이드오프가 있다.

장점: 디스크 사용량 관리
단점: 다음 배포 시 레이어 캐시 재사용 감소로 pull 시간 증가

특히 이미지 용량이 큰 상태에서 prune까지 매번 실행하면, 네트워크 상태가 좋지 않은 날에는 pull 타임아웃이 더 쉽게 발생한다.

따라서 다음과 같은 방식이 더 안전하다.

무조건 prune 대신 조건부/주기성 prune 사용
pull 재시도 로직 추가
우선 이미지 자체를 경량화해서 전송량 자체를 줄이기

5. 결과

빌드 및 배포 시간과 이미지 크기가 모두 80% 이상 감소 (약 6배 개선) 되었다.

배포시간: 1h 이상 → 10m
이미지 크기: 500mb → 50mb

Next.js 모노레포 Docker 이미지 최적화 실천기