Dockerignore: какие файлы исключить из контекста сборки

Файл .dockerignore определяет, какие файлы локального контекста не должны передаваться сборщику Docker. Он помогает убрать зависимости разработчика, кэш, историю Git и локальные настройки. Это не список файлов, которые нужно удалить из уже собранного образа.

В инструкции Mentoring.digital разберём контекст, порядок правил и проверку результата на учебной папке. Не используйте для эксперимента каталог с настоящими секретами.

Найдите корень контекста

docker build -f docker/Dockerfile .

Точка в конце задаёт текущую папку как контекст. Обычный .dockerignore ищется в её корне, даже если Dockerfile лежит в подкаталоге docker. Путь после -f и путь контекста выполняют разные задачи.

Для конкретного Dockerfile можно использовать файл с его именем и суффиксом .dockerignore рядом с ним. Например, build.Dockerfile.dockerignore относится к build.Dockerfile. Такой файл имеет приоритет над общим .dockerignore. Проверяйте, какой вариант действительно применяется вашей командой.

Начните с короткого понятного набора правил

Для учебного Node.js-проекта пример может выглядеть так. Состав исключений зависит от того, какие исходники и артефакты действительно нужны сборке.

# Локальное состояние разработки
.git
node_modules
**/node_modules
coverage
**/*.log

# Локальные параметры
.env
.env.*
!.env.example

# Документация не нужна в этом учебном образе
*.md
!README.md

Шаблон ** соответствует любому числу каталогов, включая ноль. Символ ! возвращает файл, совпавший с исключением, если дальнейшее правило снова его не исключает. Для конкретного пути решает последнее совпавшее правило.

В этом наборе .env.production исключён, а .env.example возвращён в контекст. Это допустимо только если пример действительно содержит безопасные фиктивные значения. Название example само по себе не делает содержимое безопасным.

Проверьте состав на фиктивных файлах

Создайте отдельную папку с .dockerignore, файлом main.txt, пустыми .env, .env.example, README.md и debug.log. Добавьте туда такой Dockerfile:

FROM scratch
COPY . /context/

docker buildx build --output type=local,dest=../context-review .

Экспорт должен оказаться в соседней папке context-review, вне исходного контекста. В её каталоге context проверьте наличие main.txt, .env.example и README.md и отсутствие .env и debug.log. Не помещайте результат внутрь контекста: при следующем запуске он может сам попасть в сборку.

Сравните результат после перестановки двух правил для markdown. Добавьте исключение README.md последней строкой: файл должен исчезнуть. Это маленькая проверка реального поведения, а не предположение по названию шаблона.

Не считайте .dockerignore полной защитой секретов

.gitignore влияет на Git, а .dockerignore на сборку Docker. Один файл не заменяет другой. Если секрет уже был скопирован в предыдущую сборку, новое правило не очищает старые образы, кэши и журналы. Секрет также можно случайно передать другим способом, например через аргументы сборки.

Не исключайте автоматически lock-файл зависимостей, миграции или необходимые сертификаты только ради меньшего контекста. Сначала сопоставьте правила с COPY и ADD. Если нужный путь исключён, операция копирования не сможет получить его из контекста.

На курсе Docker можно разобрать сборку своего приложения. Для ревью правил и передачи настроек выберите наставника по Docker и покажите обезличенный Dockerfile вместе с командой сборки.