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

Что такое build context и .dockerignore

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

Build context — набор файлов, который docker build передаёт сборщику; обычно это каталог, указанный последним аргументом (.). COPY видит только файлы из context, поэтому COPY ../file не работает. .dockerignore исключает файлы из context: ускоряет сборку, не ломает кэш случайными изменениями и не даёт попасть в образ node_modules, .git и .env с секретами.

Вопрос

Что такое build context и зачем нужен .dockerignore?

Что такое build context

docker build -t my-api .
#                      ^ context — текущий каталог
COPY package.json ./   # путь относительно корня context
COPY src ./src

Флаг -f меняет только путь к Dockerfile, но не context:

docker build -f docker/Dockerfile -t app .        # context — корень проекта
docker build -f docker/Dockerfile -t app docker   # context — папка docker:
                                                  # COPY package.json не найдёт файл

Чем опасен большой context

Без .dockerignore в context попадает всё:

  • node_modules — сотни мегабайт, к тому же собранные под ОС хоста (native-модули под macOS не заработают в Linux);
  • .git — история, иногда с удалёнными секретами;
  • .env — настоящие пароли;
  • dist, coverage, .nuxt, .output, логи, дампы базы.

Последствия: медленная передача context, ломающийся кэш (COPY . . видит изменение каждого лога) и утечка секретов в образ.

Пример .dockerignore для Node.js

# зависимости и артефакты сборки
node_modules
dist
.nuxt
.output
coverage
 
# git и CI
.git
.github
 
# секреты и локальные настройки
.env
.env.*
!.env.example
 
# логи и мусор
*.log
.DS_Store
 
# docker-файлы самой сборки
Dockerfile*
compose*.yaml
.dockerignore

Синтаксис похож на .gitignore: *, **, ! для исключения из исключений. Сборщик всё равно прочитает Dockerfile и .dockerignore, даже если они в списке, — просто их нельзя будет скопировать в образ через COPY.

Стратегия allowlist

Вместо перечисления лишнего можно разрешить только нужное:

*
!package.json
!package-lock.json
!tsconfig.json
!src

Так в образ гарантированно не попадёт ничего неожиданного.

Несколько контекстов

В монорепозитории иногда нужны файлы из соседнего пакета. BuildKit поддерживает именованные контексты:

docker buildx build --build-context shared=../packages/shared -t api .
COPY --from=shared . /app/shared

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

  • Не создать .dockerignore.
  • Отправить в context node_modules хоста и получить в Linux-образе бинарники под macOS.
  • Указать неправильный каталог context.
  • Исключить файл, который потом нужен для COPY, и получить ошибку «not found».

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

  • COPY работает только внутри context — выше корня выйти нельзя.
  • .dockerignore защищает одновременно скорость, кэш и секреты.
  • Для монорепозитория context обычно — корень репозитория, а Dockerfile лежит в пакете.

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

  • Последний аргумент docker build — context.
  • -f меняет Dockerfile, но не context.
  • .dockerignore: node_modules, .git, .env*, dist.
  • Allowlist через * и !.

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

Docker: Build context, Docker: .dockerignore files.

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

Поиск

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