re:re:actable
Урок 013 минуты чтения

Как упаковать Node.js-приложение в Docker

На этой странице
Кратко

Production-образ Node.js-приложения собирают multi-stage: в одном stage ставят все зависимости и компилируют TypeScript, в финальном — только production-зависимости и dist. Важные детали: lock-файл и npm ci до копирования кода (кэш), .dockerignore, запуск через node, а не npm start (сигналы), пользователь node вместо root, сервер слушает 0.0.0.0, логи идут в stdout, приложение корректно завершается по SIGTERM.

Вопрос

Как правильно упаковать Node.js-приложение (например, API на Express или NestJS) в Docker?

Production Dockerfile

# syntax=docker/dockerfile:1
 
FROM node:24-alpine AS base
WORKDIR /app
 
FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
 
FROM deps AS build
COPY . .
RUN npm run build
 
FROM base AS prod-deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
 
FROM base AS runner
ENV NODE_ENV=production
COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --chown=node:node package.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]

.dockerignore

node_modules
dist
coverage
.git
.env
.env.*
*.log
Dockerfile*
compose*.yaml

Что важно в коде приложения

const server = app.listen(Number(process.env.PORT ?? 3000), "0.0.0.0");
 
process.on("SIGTERM", () => {
  server.close(() => {
    db.end().finally(() => process.exit(0));
  });
});
  • Слушать 0.0.0.0, иначе опубликованный порт не будет работать.
  • Обрабатывать SIGTERM: docker stop и любые оркестраторы останавливают контейнер именно им.
  • Конфигурацию читать из переменных окружения, а не из файла в образе.
  • Логировать в stdout в формате JSON — их соберёт Docker или платформа.

Почему node, а не npm start

CMD ["npm", "start"] делает PID 1 процесс npm, а Node.js — его потомком. npm ненадёжно пересылает сигналы, поэтому приложение может не получить SIGTERM и будет убито через 10 секунд. Запускайте node напрямую или добавьте init: true (tini) — подробнее в уроке про PID 1.

Выбор базового образа

ОбразРазмерОсобенности
node:24~1 ГБПолный Debian — для сборки с компиляторами
node:24-slim~250 МБDebian без лишнего, glibc — совместим с большинством native-модулей
node:24-alpine~150 МБmusl libc: некоторые native-модули (sharp, bcrypt, Prisma) требуют особых бинарников
gcr.io/distroless/nodejs24-debian12~130 МБНет shell и пакетного менеджера — минимальная поверхность атаки, сложнее отладка

Если с Alpine возникают ошибки загрузки native-модулей, первым делом пробуют -slim.

pnpm и монорепозиторий

FROM node:24-alpine AS base
RUN corepack enable
WORKDIR /app
 
FROM base AS build
COPY . .
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile
RUN pnpm --filter api build
RUN pnpm --filter api deploy --prod /out   # изолированный пакет с prod-зависимостями
 
FROM node:24-alpine AS runner
WORKDIR /app
COPY --from=build /out .
USER node
CMD ["node", "dist/main.js"]

pnpm deploy собирает каталог только с нужным пакетом и его зависимостями — без всего монорепозитория.

Частые ошибки

  • COPY . . до npm ci — нет кэша.
  • npm install вместо npm ci — невоспроизводимые версии.
  • .env в образе.
  • Сервер на localhost внутри контейнера.
  • devDependencies и исходники в финальном образе.
  • Копирование node_modules с хоста (бинарники под другую ОС).

Что важно помнить

  • Финальный образ = runtime + prod-зависимости + dist + USER + CMD.
  • Graceful shutdown — ответственность кода приложения, Docker лишь посылает сигнал.
  • NODE_ENV=production меняет поведение многих библиотек (Express, логгеры), поэтому задаётся в runtime-образе.

Мини-шпаргалка

  • Multi-stage: deps → build → prod-deps → runner.
  • npm ci, cache mount, .dockerignore.
  • CMD ["node", "dist/main.js"], USER node.
  • 0.0.0.0, SIGTERM, stdout.

Документация

Docker: Containerize a Node.js application, Node.js: Docker best practices.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам