SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor

Docker Compose: build и image на VPS

Поймите разницу между image и build в Docker Compose: почему compose up не видит изменения Dockerfile и когда нужны docker compose build и pull.

Docker Compose: build и image — краткий ответ

В файле Docker Compose параметр image: указывает образ, который нужно использовать. Это может быть локальный образ, образ с тегом или ссылка на digest. Параметр build: указывает Compose, как собрать образ из исходных файлов. Если задан только image:, Compose использует или загружает образ в соответствии с pull_policy. Если задан только build:, Compose собирает образ настроенным сборщиком и присваивает ему имя, сформированное из имени проекта и имени сервиса. Если заданы оба параметра, pull_policy определяет, загружать образ или собирать его. При сборке Compose помечает результат именем из image:. Так образ можно собрать и отправить под выбранным вами именем. Сборщик может работать локально или на удалённом Docker host.

В этом заключается всё различие. Ниже описано, как это работает на сервере. Предполагается, что Docker Engine и Compose plugin уже установлены; в статье о запуске Docker на VPS описана эта часть.

Три формы полностью

Используйте опубликованный tag. Если образ отсутствует, он будет загружен согласно политике pull по умолчанию. Dockerfile не используется.

services:
  web:
    image: nginx:1.27
    restart: unless-stopped
    ports:
      - "80:80"

Соберите образ из Dockerfile в каталоге проекта. Во время сборки также могут быть загружены образы и зависимости, необходимые Dockerfile.

services:
  web:
    build: .
    restart: unless-stopped
    ports:
      - "80:80"

Соберите образ и присвойте результату tag docker compose build. Если политика pull явно не задана, up пытается загрузить этот образ перед его сборкой. Затем docker compose push может отправить этот tag в registry без изменений.

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: registry.example.com/acme/web:1.4.2
    restart: unless-stopped
    ports:
      - "80:80"

context — это каталог, передаваемый builder. dockerfile вычисляется относительно этого контекста, поэтому использование context: . вместе с dockerfile: docker/prod.Dockerfile является нормальным и корректным. Выполните docker compose images, чтобы увидеть имя образа и image ID для каждого service container. Проверьте Compose file и убедитесь, использует ли сервис image:, build: или оба варианта.

Почему docker compose up не пересобирает образ после изменения Dockerfile?

Обычная команда up повторно использует существующий образ, если явно не запросить сборку или не настроить политику, которая требует её выполнения.

Если у сервиса указана только секция build:, Compose использует существующий образ, если он доступен. Он не читает Dockerfile, не сравнивает исходные файлы и не проверяет метки времени. Если указаны image: и build:, но не задан параметр pull_policy, Compose сначала пытается выполнить pull, а затем собирает образ, если образ недоступен в registry или кэше платформы. Наличие образа считается достаточным условием.

Поэтому вы изменяете app.py, запускаете docker compose up -d, видите в выводе Compose запущенный контейнер и получаете старый код. Ошибки не произошло, поэтому предупреждение не выводится. На это указывает статус рядом с именем контейнера: если Compose заменил контейнер, он сообщает recreated или started, а если решил оставить контейнер без изменений — running.

Две проверки позволяют точно установить причину. docker compose images выводит ID образа, который использует каждый контейнер. Запишите его перед развёртыванием и сравните после него. В выводе docker image ls есть столбец CREATED, но кэшированные сборки и воспроизводимые метки времени означают, что одной этой даты недостаточно, чтобы подтвердить сборку последней версии исходного кода.

Какие флаги принудительно запускают сборку

  • docker compose up -d --build сначала выполняет сборку, а затем пересоздаёт контейнеры с изменившимся образом. Обычно нужен именно этот флаг.
  • docker compose build web собирает один сервис и ничего не запускает. После него используйте docker compose up --no-deps -d web, чтобы заменить только этот контейнер и оставить остальной стек запущенным.
  • docker compose build --no-cache web отключает использование кэшированных слоёв и пересобирает сервис.
  • docker compose build --pull пытается загрузить более новую версию базового образа в FROM. Поэтому плавающий тег, например node:22, получает текущее содержимое образа вместо копии, загруженной в марте.
  • docker compose up -d --force-recreate принудительно пересоздаёт контейнер, даже если конфигурация и образ не изменились. Сам по себе этот флаг не запрашивает сборку, но up всё равно может выполнить её, если образ отсутствует или политика загрузки этого требует. Часто этот флаг используют по ошибке вместо --build, что приводит в тупик.

Решение также можно перенести в файл. Согласно спецификации Compose, pull_policy: build означает, что Compose собирает образ и пересобирает его, если образ уже существует. Поэтому каждый запуск up требует сборки. На ноутбуке это может быть нужно, но на сервере — редко.

services:
  web:
    build: .
    image: registry.example.com/acme/web:dev
    pull_policy: build

Нужно учитывать ещё одно взаимодействие флагов. docker compose pull пытается загрузить образы также для сервисов, у которых есть секция build. Если загрузка завершается ошибкой, он сообщает, что образ нужно собрать. Передайте --ignore-buildable, чтобы молча пропустить такие сервисы.

Как build cache определяет время деплоя

Builder проверяет каждую инструкцию Dockerfile и ищет пригодный для повторного использования результат в кэше, если инструкция и её входные данные не изменились. Для COPY входные данные включают содержимое файлов и метаданные, но не время изменения. После первого промаха кэша последующие шаги, зависящие от него, выполняются заново.

Это правило определяет, займёт ли деплой несколько секунд или несколько минут. Располагайте инструкции Dockerfile от тех, которые меняются редко, к тем, которые меняются при каждом commit.

FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]

npm ci находится перед COPY . ., поэтому изменение исходного файла оставляет слой установки в кэше, и сборка продолжается с шага копирования. Если поменять эти две строки местами, изменение одного символа заново установит все зависимости, потому что COPY . . делает недействительным слой, на котором основан npm ci. Такая же структура применяется к pip install -r requirements.txt и go mod download.

--no-cache подходит, если вы подозреваете, что устаревший слой скрывает внесённое исправление. Но использовать его по умолчанию не стоит: он удаляет повторное использование слоёв, ради которого выстраивается порядок инструкций Dockerfile.

Есть одна настройка, которую image sets и Compose могут переопределить: CMD в Dockerfile определяет, что image запускает по умолчанию, а ключ command: в service заменяет это значение. В этом случае важен материал Как взаимодействуют command и entrypoint, поскольку переопределение в Compose может заставить только что собранный image вести себя точно так же, как старый.

Контекст сборки и .dockerignore

context: . предоставляет сборщику каталог проекта. Без исключений в него входят .git и любые каталоги с данными, которые находятся рядом с исходным кодом. При этом BuildKit пропускает неиспользуемые файлы и передаёт изменения инкрементально. Если сборка неизменённого проекта надолго останавливается на этапе передачи контекста, это означает, что контекст слишком большой.

Файл .dockerignore в корне контекста исключает пути из этой передачи. Синтаксис близок к .gitignore.

.git
node_modules
*.log
data/
.env

Это даёт два преимущества. Передаваемый объём уменьшается, поэтому такие файлы отправляются быстрее. Кроме того, COPY . . больше не сможет скопировать .env в образ, где любой пользователь, загрузивший этот образ, сможет прочитать эти данные.

Причиной замедления сборки, которое со временем усиливается, может быть bind mount. Именованный том находится за пределами каталога проекта, но bind mount, например ./data:/var/lib/postgresql/data, находится внутри контекста сборки. Поэтому сборки каждую неделю становятся медленнее по мере роста базы данных. Одной строки в .dockerignore достаточно, чтобы устранить проблему. В разделе Bind mounts и именованные тома рассматриваются более общие компромиссы.

Аргументы сборки несут меньший вариант того же риска. Значения, переданные через args:, могут сохраняться в истории образа или метаданных provenance. Поэтому указывайте там номер версии, но никогда не указывайте токен. Предопределённые proxy-аргументы по умолчанию исключаются из кэша сборки и docker history, если только на них явно не ссылаются в Dockerfile. В разделе Файлы окружения и секреты в Compose объясняется, где вместо этого следует хранить учётные данные.

Собирать на VPS или в другом месте с последующей загрузкой?

Сборка на сервере, который обслуживает ваш трафик, используется по умолчанию, потому что это самый короткий путь: git pull, затем docker compose up -d --build. Это допустимо для небольшого сервера, от которого пока никто не зависит. Такой подход перестаёт быть приемлемым по двум измеримым причинам и по одной причине, которая проявляется только в плохой день.

Память. Сборка запускает компиляторы и bundler рядом с работающим приложением, а именно они потребляют много памяти в большинстве стеков. JavaScript bundler или сборка Rust могут исчерпать память, доступную на VPS с 1 GB. При исчерпании памяти ядро выбирает процесс-жертву OOM по показателю badness, который учитывает использование памяти, контекст выделения и oom_score_adj; ядро не просто завершает самый большой процесс. Сборка может завершиться с Killed и кодом выхода 137, либо вместо неё может быть завершена база данных, из-за чего сайт перестанет работать в середине развёртывания. dmesg -T | grep -i oom ищет сообщения OOM в журнале ядра; для доступа требуется разрешение на чтение этого журнала.

Диск. После сборки остаются слои образов и кэш сборки. docker system df показывает, сколько места они занимают; периодическая сборка мусора BuildKit удаляет кэш в соответствии с настроенными политиками. Освободите место с помощью docker image prune для dangling images и docker builder prune для слоёв кэша. Заполненный диск останавливает не только сборку. База данных также перестаёт записывать данные, и такая ошибка обходится значительно дороже, чем медленное развёртывание.

Воспроизводимость. Если образ не отправить и не экспортировать, он существует только на сервере, где был собран. Если старый образ больше недоступен, для отката нужно переключиться на старый commit и выполнить сборку снова. При этом нет гарантии, что результат будет таким же, потому что base tag изменился, а package mirrors обновились вместе с ним. При сборке в другом месте и отправке tag откат превращается в редактирование: укажите image: предыдущий tag и выполните docker compose up -d.

Надёжная схема проста. Ваша continuous integration выполняет сборку и отправляет registry.example.com/acme/web:<git-sha>, а Compose-файл на VPS содержит image: и вообще не содержит ключа build:. После этого развёртывание выполняется двумя командами, которым требуется почти никакая память.

docker compose pull
docker compose up -d

Выполните docker login registry.example.com на сервере, чтобы сохранить учётные данные для загрузки private tags.

Сохраните секцию сборки для разработки, а не удаляйте её, в файле с выбранным вами именем.

# compose.dev.yaml
services:
  web:
    build:
      context: .
    pull_policy: build
docker compose -f compose.yaml -f compose.dev.yaml up -d --build

Назовите этот файл compose.dev.yaml, а не compose.override.yaml. Compose автоматически загружает override-файл, если он присутствует, поэтому случайно скопированный на сервер override-файл незаметно снова запустит сборку на сервере. В разделе Объединение нескольких Compose-файлов объясняется, как при слиянии определяется значение каждого ключа.

Ошибка архитектуры при сборке в другой среде

Один образ платформы содержит архитектуру CPU, для которой он был собран. Если собрать ARM-образ на ноутбуке с Apple Silicon, отправить его в реестр, а затем использовать этот образ на VPS с архитектурой x86_64, Docker предупредит при создании контейнера, если использует несовместимый кэшированный образ без явно заданной платформы. Без эмуляции процесс завершается с ошибкой exec format error. Это выглядит как повреждённый бинарный файл, но им не является. Явно укажите целевую платформу при сборке:

docker buildx build --platform linux/amd64 \
  -t registry.example.com/acme/web:1.4.2 --push .

Такая же несовместимость возникает в обратной ситуации, если ноутбук использует x86, а вы запускаете ARM VPS вместо VPS с архитектурой x86. Если поручить CI выполнять сборку на архитектуре, на которой выполняется развёртывание, проблема исчезает. Её также решает мультиплатформенный образ: при загрузке Docker выбирает подходящий вариант.

Что проверить после развёртывания

  • docker compose images выводит образ и тег каждого запущенного контейнера. Изменившийся ID образа подтверждает, что новая сборка используется.
  • docker compose config выводит объединённый файл после подстановки переменных. Так вы можете проверить итоговое имя образа, которое будет использовать Compose, до запуска.
  • docker compose logs -f web в течение первых 30 секунд после замены. Контейнер, который запускается и сразу завершается, перезапускается только при соответствующей политике перезапуска. Проверьте журналы, чтобы найти причину.
  • docker image ls показывает столбец CREATED. Также проверьте вывод сборки и ID развёрнутого образа, поскольку одна только временная метка создания не подтверждает выполнение пересборки.

Если вы ещё собираете файл, к которому относятся эти проверки, в материале основы файла Compose на VPS описаны связанные ключи, а в шпаргалке команд Compose перечислены остальные подкоманды.

FAQ

Можно ли использовать build и image в одном сервисе?

Да, это стандартная конфигурация для проекта, который вы собираете самостоятельно. Когда Compose выполняет сборку из раздела build:, он присваивает результату значение image:. Если pull_policy не задан, up сначала пытается выполнить pull. Этот tag используется командой docker compose push для отправки образа в registry, а другая машина использует его для загрузки образа. Без ключа image: Compose всё равно выполняет сборку, но называет образ по имени проекта и сервиса. При этом он предупреждает, что отсутствие этого атрибута не позволяет отправить образ в registry.

Почему docker compose up не учитывает изменения в Dockerfile?

Потому что обычная команда up повторно использует существующий образ, если явно не запросить сборку или не настроить policy, которая её требует. Она не сравнивает образ с Dockerfile или исходными файлами, чтобы определить, нужна ли повторная сборка. Выполните docker compose up -d --build или выполните docker compose build web, а затем docker compose up --no-deps -d web, чтобы пересоздать один сервис. Параметр pull_policy: build для сервиса заставляет выполнять сборку при каждом запуске up. Это подходит для машины разработки.

В чём разница между --build и --force-recreate?

--build повторно собирает образ, а затем пересоздаёт контейнеры, образ которых изменился. --force-recreate принудительно пересоздаёт контейнеры, даже если конфигурация и образ не изменились. Сам по себе этот параметр не запускает сборку. Если изменения внесены в исходный код или Dockerfile, нужен параметр --build. --force-recreate используется для сброса самого контейнера, например для очистки его доступного для записи слоя при сохранении того же образа.

Следует ли собирать Docker images на VPS или в другом месте?

Собирайте образы в другом месте и загружайте tag после того, как сервер начнёт обслуживать traffic. Сборка конкурирует с приложением за память. При исчерпании памяти kernel выбирает процесс для завершения по настраиваемому OOM score. Под его действие может попасть сборка или database. Сборки также оставляют cache на диске, хотя BuildKit автоматически удаляет его в соответствии со своими garbage collection policies. Сборка на сервере допустима для небольшого проекта без пользователей. Позже перенос не вызовет значительных проблем, если хранить раздел build: в Compose file, предназначенном только для разработки.

Как предотвратить заполнение диска Docker build cache?

Выполните docker system df, чтобы узнать, сколько места занимают images и build cache. Команда docker builder prune удаляет cached layers, а docker image prune — dangling images, оставшиеся после предыдущих сборок. Добавление -a удаляет весь неиспользуемый build cache или все images, на которые не ссылаются контейнеры, соответственно. Это не гарантирует, что следующая сборка полностью начнётся без cache. Не добавляйте docker system prune -af --volumes в расписание на сервере: команда удаляет остановленные контейнеры и неиспользуемые anonymous volumes. Поэтому во время обслуживания database data в anonymous volume может быть утрачена.

Была ли эта статья полезной?