# lock(package-lock.json)을 쓰고 검사하는 npm 은 한 버전으로 고정한다.
# npm 은 버전마다 lock 의 중첩 항목(chokidar·readdirp·@emnapi 등)을 다르게 정리해서, 섞어 쓰면 lock 이 매번 바뀐다.
# 바꿀 때는 frontend/Dockerfile · .github/workflows/ci.yml 의 NPM_VERSION · docker 스킬 문서를 함께 고친다.
ARG NPM_VERSION=11.6.2

# 런타임은 Node 24 LTS — 패치까지 고정한다 (메이저 태그는 빌드할 때마다 그날의 최신 패치를 받는다).
# 갱신 규칙(일반 패치는 배포 2주 뒤, 보안 릴리스는 CI 통과 즉시)과 함께 고치는 곳은 docker 스킬 문서 "Node 버전" 참조.
ARG NODE_VERSION=24.22.1

FROM node:${NODE_VERSION}-alpine3.24 AS builder
ARG NPM_VERSION
WORKDIR /app

# 전역 설치는 root 권한이 필요하므로 USER 전환 전에 수행
RUN npm install -g npm@${NPM_VERSION}

# 개발 환경(docker-compose.dev.yml)은 이 스테이지를 그대로 구동하므로 비-root 로 전환한다.
# /app 소유권을 넘겨야 익명 볼륨(node_modules)도 node 소유로 생성되어 캐시 쓰기가 가능하다.
RUN chown node:node /app
USER node

# 재현 가능한 빌드를 위해 npm ci 사용 (lockfile 기반)
COPY --chown=node:node package*.json ./
RUN npm ci

COPY --chown=node:node . .
RUN npm run build
# 대용량 첨부 파일 위치(FILE_STORAGE_DIR=/app/files — 11단계) — dev 는 이 단계에 named volume <PROJECT_NAME>_files 를 붙인다.
# 새 볼륨은 이 디렉터리의 소유자(node)를 물려받는다 (없으면 root 소유로 생겨 node 가 쓰지 못한다). 빌드 컨텍스트의 files/ 는 .dockerignore 가 뺀다
RUN mkdir -p /app/files

FROM node:${NODE_VERSION}-alpine3.24 AS production
ARG NPM_VERSION
WORKDIR /app

ENV NODE_ENV=production

# 운영 stage 도 동일 npm 버전 사용
RUN npm install -g npm@${NPM_VERSION}

# 운영용 의존성만 설치
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=builder /app/dist ./dist
# 업데이트 내역 글(글 파일 하나가 글 하나 — 계약 7절) — 서버가 기동 · 요청 때 /app/release-notes 를 읽기만 한다(modules/release-notes — 쓰지 않는다)
COPY --from=builder /app/release-notes ./release-notes

# 업로드 저장 위치(compose 의 UPLOAD_DIR=/app/uploads)와 대용량 첨부 파일 위치(FILE_STORAGE_DIR=/app/files — 11단계) — node 소유로 만들어 둔다.
# 운영 compose 는 여기에 named volume 을 붙이는데, 새 볼륨은 이 디렉터리의 소유자를 물려받아 node 가 쓸 수 있다.
# (호스트 디렉터리를 바인드 마운트하면 sudo docker compose 가 root 소유로 만들어 업로드가 실패한다)
RUN mkdir -p /app/uploads /app/files && chown node:node /app/uploads /app/files

EXPOSE 3000

# 비-root 실행 (보안 규칙)
USER node

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