Шапка Docker: назначение и виды¶

Шапка Docker — это жаргонное название верхней части файла конфигурации Dockerfile, содержащей инструкции, которые задают базовый образ, метаданные и начальную настройку окружения сборки. В профессиональной среде под «шапкой» чаще всего понимают совокупность первых директив файла — прежде всего FROM, а также сопутствующих ARG, LABEL, MAINTAINER (устаревшая), комментариев и служебных указаний. Именно эта часть определяет, на какой основе будет строиться образ и какие параметры унаследует итоговый контейнер.

¶Назначение и место в структуре Dockerfile

Dockerfile — текстовый сценарий, по которому команда docker build собирает образ. Инструкции выполняются сверху вниз, и первая значащая директива обязана быть FROM (за исключением редкого случая сборки «с нуля» через FROM scratch). Всё, что расположено до неё, — комментарии и объявления ARG. Эту начальную секцию и называют шапкой.

Шапка выполняет несколько задач:

• задаёт базовый образ и его версию (тег или дайджест);
• объявляет аргументы сборки, доступные до этапа FROM;
• фиксирует метаданные: автора, лицензию, описание, контакты;
• определяет точку отсчёта для многоступенчатой (multi-stage) сборки.

Корректная шапка напрямую влияет на воспроизводимость сборки: без точного тега базового образа результат может отличаться на разных машинах и в разное время.

¶Основные инструкции шапки

¶FROM

Ключевая директива. Синтаксис: FROM <образ>[:<тег>] [AS <имя_этапа>]. Пример: FROM python:3.12-slim AS builder. Указание конкретного тега предпочтительнее расплывчатого latest, поскольку последний не гарантирует стабильность. Для максимальной воспроизводимости применяют дайджест: FROM alpine@sha256:....

В multi-stage сборке несколько FROM открывают несколько этапов; имя после AS позволяет ссылаться на предыдущий этап при копировании артефактов (COPY --from=builder).

¶ARG

ARG объявляет переменную, доступную во время сборки. Особенность: аргумент, объявленный до первого FROM, действует только в рамках шапки, поэтому его часто повторяют внутри этапа. Типичный приём — параметризация версии базового образа:

`` ARG BASE_VERSION=3.12 FROM python:${BASE_VERSION}-slim ``

¶LABEL

LABEL добавляет метаданные в образ в формате «ключ=значение». Распространённые ключи: maintainer, org.opencontainers.image.version, org.opencontainers.image.source, description. Метаданные видны через docker inspect и используются системами оркестрации и реестрами.

¶MAINTAINER

Устаревшая инструкция для указания автора. Считается deprecated и вытеснена LABEL maintainer=.... В новых файлах не применяется.

¶Типичные ошибки

• Использование latest вместо фиксированного тега — приводит к неожиданным изменениям поведения при пересборке.
• Объявление ARG до FROM без повторного объявления внутри этапа — переменная окажется недоступной в инструкциях RUN.
• Размещение тяжёлых операций в шапке — увеличивает размер образа и время сборки; слои кэшируются, но их порядок влияет на эффективность.
• Отсутствие метаданных LABEL — затрудняет сопровождение и аудит образов в реестре.

¶Шапка и кэширование слоёв

Docker кэширует каждый слой. Если шапка меняется (например, обновлён тег базового образа), все последующие слои пересобираются заново. Поэтому директивы, меняющиеся редко — FROM, LABEL, — размещают в начале, а часто изменяемые (копирование исходного кода, установка зависимостей проекта) — ниже. Такой порядок сокращает время повторных сборок в CI/CD.

¶Практический пример

```

¶Шапка файла

ARG NODE_VERSION=20 FROM node:${NODE_VERSION}-alpine AS build LABEL org.opencontainers.image.title="example-app" \ org.opencontainers.image.version="1.0.0"

WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build ```

Здесь шапка — строки от ARG до LABEL включительно. Далее идёт рабочая часть: установка зависимостей и сборка приложения.

¶Значение для DevOps-практик

В корпоративной разработке шапку стандартизируют: компании вводят шаблоны Dockerfile, где базовые образы берутся из внутреннего реестра, а метаданные заполняются автоматически в конвейере. Это упрощает сканирование уязвимостей, контроль лицензий и переход на обновлённые базовые образы. Единый формат шапки также облегчает ревью и автоматическую проверку файлов линтерами (например, hadolint).

В российской практике при импортозамещении инфраструктуры базовые образы нередко берут из локальных реестров и зеркал, а в шапке фиксируют отечественные дистрибутивы на основе Linux. Это снижает зависимость от внешних источников и ускоряет загрузку образов внутри корпоративной сети.

¶Связанные понятия

Шапка тесно связана с такими темами, как базовый образ, многоступенчатая сборка, реестр контейнеров, слои образа и переменные сборки. Понимание её устройства — базовый навык при работе с контейнеризацией и развёртыванием приложений.

Источники: официальная документация Docker по Dockerfile и инструкциям FROM, ARG, LABEL; материалы по лучшим практикам написания Dockerfile; документация линтера hadolint.