Какие инструкции 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.