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

Какие инструкции Dockerfile нужно знать

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

Базовый набор: FROM — базовый образ, WORKDIR — рабочий каталог, COPY — файлы из build context, RUN — команда при сборке, ENV — переменная в образе и контейнере, ARG — переменная только сборки, USER — пользователь, EXPOSE — документация порта, CMD и ENTRYPOINT — команда запуска, HEALTHCHECK — проверка здоровья. Для каждой инструкции важно понимать, когда она выполняется: при сборке или при запуске.

Вопрос

Какие инструкции Dockerfile нужно знать и что делает каждая?

Сводная таблица

ИнструкцияКогда работаетЧто делает
FROMСборкаБазовый образ; несколько FROM — multi-stage
WORKDIRСборка и запускКаталог для RUN, COPY, CMD; создаётся, если его нет
COPYСборкаКопирует файлы из context или другого stage
ADDСборкаКак COPY, плюс URL и распаковка tar — используют редко
RUNСборкаВыполняет команду, результат сохраняется слоем
ENVСборка и запускПеременная окружения, остаётся в образе
ARGТолько сборкаПараметр сборки (--build-arg), в контейнере его нет
USERСборка и запускПользователь для следующих RUN и для процесса
EXPOSEМетаданныеДокументирует порт, не публикует его
CMDЗапускКоманда или аргументы по умолчанию
ENTRYPOINTЗапускИсполняемый файл контейнера
HEALTHCHECKЗапускПериодическая проверка состояния
LABELМетаданныеПроизвольные метки: версия, автор, ссылка на репозиторий
VOLUMEЗапускОбъявляет точку монтирования, создаёт анонимный volume
STOPSIGNALЗапускСигнал для docker stop вместо SIGTERM

Пример со всеми основными инструкциями

# syntax=docker/dockerfile:1
ARG NODE_VERSION=24
FROM node:${NODE_VERSION}-alpine
 
LABEL org.opencontainers.image.source="https://github.com/team/api"
 
WORKDIR /app
ENV NODE_ENV=production
 
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
COPY --chown=node:node dist ./dist
 
USER node
EXPOSE 3000
 
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
 
CMD ["node", "dist/main.js"]

Ключевые нюансы

RUN и CMD. RUN npm ci выполняется один раз при docker build. CMD ["node", "dist/main.js"] — каждый раз при docker run.

EXPOSE не открывает порт. Это документация для людей и инструментов. Доступ с хоста даёт только -p или ports в Compose.

ARG до и после FROM. ARG, объявленный до FROM, доступен только в строке FROM. Чтобы использовать его внутри stage, его объявляют повторно после FROM.

USER и права. После USER node файлы, скопированные COPY без --chown, принадлежат root — приложение не сможет в них писать.

HEALTHCHECK и утилиты. В alpine есть wget из BusyBox, в slim и distroless нет ни wget, ни curl. Тогда проверку пишут на самом Node.js: CMD ["node", "healthcheck.js"].

Exec- и shell-форма. CMD ["node", "app.js"] запускает процесс напрямую. CMD node app.js оборачивает его в /bin/sh -c, и сигналы docker stop до Node.js не доходят.

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

  • Путать RUN и CMD.
  • Считать, что EXPOSE пробрасывает порт.
  • Передавать секреты через ARG или ENV — они остаются в истории и метаданных образа.
  • Использовать ADD там, где достаточно COPY.
  • Не задавать WORKDIR и работать в /.

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

  • Сборочные инструкции (RUN, COPY) создают слои, остальные — метаданные.
  • ENV попадает в образ и виден через docker inspect; ARG в итоговом контейнере не существует, но может остаться в истории сборки.
  • Сравнение похожих пар — в уроках CMD и ENTRYPOINT и COPY/ADD, ARG/ENV.

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

  • Сборка: FROM, RUN, COPY, ARG.
  • Запуск: CMD, ENTRYPOINT, HEALTHCHECK.
  • И там и там: WORKDIR, ENV, USER.
  • EXPOSE — только документация.
  • Exec-форма ["..."] для CMD и ENTRYPOINT.

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

Docker: Dockerfile reference, Docker: Building best practices.

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

Поиск

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