Docker Compose: build проти image на VPS
Пояснюємо різницю між build та image у Docker Compose на VPS: чому compose up ігнорує зміни Dockerfile та як примусово перебудувати образ.
Docker Compose: build проти image — коротка відповідь
У файлі Docker Compose image: визначає образ, який потрібно використовувати, зокрема локальний образ, тег або посилання на digest, а build: вказує Compose, як зібрати образ із вихідного коду. Якщо задано лише image:, Compose використовує або завантажує образ відповідно до pull_policy. Якщо задано лише build:, Compose збирає образ за допомогою налаштованого builder і надає йому ім’я, сформоване з імені проєкту та сервісу. Якщо задано обидва параметри, pull_policy визначає, чи завантажувати образ, чи збирати його; під час збірки результат отримує тег з іменем у image:. Саме так можна зібрати образ і відправити його під вибраним вами іменем. Builder може працювати локально або на віддаленому Docker host.
У цьому полягає вся відмінність. Нижче описано, як це працює на сервері. Передбачається, що Docker Engine і Compose plugin уже встановлені; у матеріалі про запуск Docker на VPS описано цю частину.
Усі три форми повністю
Використовуйте опублікований тег. Якщо його немає, він завантажується відповідно до стандартної політики 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"Збірка з тегуванням результату через docker compose build. Без явно заданої політики pull up намагається завантажити цей образ перед його збіркою. Після цього docker compose push може надіслати саме цей тег до 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, щоб побачити назву образу та ID образу для кожного контейнера сервісу; перевірте файл Compose, щоб підтвердити, чи використовує сервіс image:, build: або обидва.
Чому docker compose up не перебудовує образ після зміни Dockerfile?
Тому що звичайний up повторно використовує наявний образ, якщо явно не запросити складання або не налаштувати політику, яка його вимагає.
Коли Compose запускає сервіс, у якому є лише секція build:, він використовує наявний образ, якщо той доступний. Він не читає ваш Dockerfile, не порівнює файли вихідного коду й не перевіряє часові мітки. Якщо задано і image:, і build:, а явний pull_policy відсутній, Compose спочатку намагається завантажити образ, а потім виконує складання, якщо образ недоступний у registry або кеші платформи. Наявності образу достатньо.
Ви змінюєте app.py, виконуєте docker compose up -d, бачите вивід Compose про запущений контейнер і продовжуєте обслуговувати старий код. Помилки не сталося, тому Compose нічого не повідомив. Показовим є слово стану, яке Compose виводить поруч з іменем контейнера: для контейнера, який Compose замінив, буде вказано recreated або started, а для контейнера, який Compose вирішив не змінювати, — 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усе одно може виконати його, якщо образ відсутній або політика pull цього вимагає. Часто цей прапорець помилково використовують замість--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, щоб без повідомлень пропустити такі сервіси.
Як кеш збірки визначає тривалість розгортання
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: . робить каталог проєкту доступним для builder. Без винятків це також включає .git і будь-який каталог із даними, який ви зберігаєте поруч із вихідним кодом, хоча BuildKit пропускає невикористовувані файли та передає зміни інкрементально. Якщо збирання призупиняється на етапі передавання контексту в проєкті, який не змінювався, це означає, що контекст надто великий.
Файл .dockerignore у корені контексту виключає шляхи з цього передавання. Синтаксис подібний до .gitignore.
.git
node_modules
*.log
data/
.envЦе дає дві переваги. Передавання стає меншим, тому на надсилання цих файлів витрачається менше часу. Крім того, COPY . . більше не зможе скопіювати .env в image, де будь-хто, хто завантажить цей image, зможе прочитати його.
Причиною поступового уповільнення збирання може бути bind mount. Іменований volume розташований за межами каталогу проєкту, але bind mount, наприклад ./data:/var/lib/postgresql/data, міститься всередині контексту збирання. Тому збирання щотижня стає повільнішим у міру зростання бази даних. Один рядок у .dockerignore усуває проблему. У розділі Bind mounts іменованих volume розглянуто ширший компроміс.
Build arguments мають менший, але подібний ризик. Значення, передані через args:, можуть зберігатися в історії image або в метаданих provenance. Тому передавайте там номер версії, а не token. Попередньо визначені proxy arguments за замовчуванням виключаються з build cache і docker history, якщо їх явно не вказано в Dockerfile. У розділі Env-файли та секрети в Compose пояснено, де натомість зберігати облікові дані.
Чи варто збирати на VPS, чи збирати в іншому місці та завантажувати образ?
Збірка на сервері, який обслуговує ваш трафік, є типовим варіантом, оскільки це найкоротший шлях: git pull, потім docker compose up -d --build. Це прийнятно для невеликого сервера, від якого поки ніхто не залежить. Однак такий підхід має два вимірювані недоліки та ще один, який проявляється лише в невдалий момент.
Пам’ять. Під час збірки компілятори й bundler-и працюють поруч із вашим активним застосунком, а саме вони споживають найбільше пам’яті в більшості стеків. JavaScript bundler або компіляція Rust можуть вичерпати доступну пам’ять на VPS із 1 GB. Коли пам’ять вичерпано, kernel вибирає процес для завершення за оцінкою badness, яка залежить від використання пам’яті, контексту виділення та oom_score_adj; він не просто завершує найбільший процес. Збірка може завершитися з Killed і кодом виходу 137, або замість неї може бути завершено database, через що сайт стане недоступним у процесі розгортання. dmesg -T | grep -i oom шукає повідомлення про OOM у журналі kernel; для доступу потрібні права на читання цього журналу.
Диск. Після збірок залишаються image layers і build cache. docker system df показує використання диска; періодичне garbage collection у BuildKit очищає cache відповідно до налаштованих політик. Очистіть його за допомогою docker image prune для dangling images і docker builder prune для cached layers. Заповнений диск зупиняє не лише збірку. Database також припиняє запис, а така відмова коштує значно дорожче, ніж повільне розгортання.
Відтворюваність. Якщо не push-нути або не export-нути образ, образ, зібраний на сервері, існує лише на цьому сервері. Якщо старий образ більше недоступний, відкат означає checkout старого commit і повторну збірку. Немає гарантії, що вона дасть той самий результат, оскільки base tag змінився, а package mirrors змінилися разом із ним. Збірка в іншому місці та push tag перетворюють відкат на редагування: вкажіть image: на попередній tag і виконайте docker compose up -d.
Надійна схема проста. Ваша continuous integration виконує збірку та push-ить registry.example.com/acme/web:<git-sha>, а Compose file на VPS містить image: і взагалі не містить ключа build:. Тоді розгортання зводиться до двох команд, які майже не споживають пам’яті.
docker compose pull
docker compose up -dВиконайте docker login registry.example.com на сервері, щоб зберегти облікові дані для pull приватних tag-ів.
Залиште секцію build для development, а не видаляйте її, у файлі з назвою на ваш вибір.
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildНазвіть цей файл compose.dev.yaml, а не compose.override.yaml. Compose автоматично завантажує override file, якщо він присутній, тому випадково скопійований на сервер override тихо знову запустить збірку на ньому. У розділі Накладання кількох Compose files пояснюється, як під час об’єднання визначається значення кожного ключа.
Пастка архітектури під час складання в іншому середовищі
Один образ платформи містить архітектуру CPU, для якої його було складено. Якщо скласти ARM-образ на ноутбуці з Apple Silicon, передати його до реєстру, а потім використати цей образ на x86_64 VPS, Docker попередить під час створення контейнера, якщо застосує несумісний кешований образ без явно вказаної платформи. Без емуляції процес завершується помилкою exec format error. Вона виглядає як повідомлення про пошкоджений бінарний файл, але таким не є. Явно складіть образ для цільової платформи:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .Та сама невідповідність виникає у зворотному напрямку, якщо ваш ноутбук працює на x86, а ви запускаєте ARM VPS, а не x86 VPS. Якщо доручити CI складати образ на архітектурі, на якій ви його розгортаєте, це усуває проблему. Мультиплатформний образ також вирішує її: під час завантаження Docker вибирає відповідний варіант.
Що перевірити після розгортання
docker compose imagesвиводить image і tag для кожного запущеного контейнера. Змінений image ID підтверджує, що нова збірка вже використовується.docker compose configвиводить об’єднаний файл після підстановки змінних. Так можна перевірити остаточне ім’я image, яке використовуватиме Compose, до запуску.docker compose logs -f webпротягом перших 30 секунд після заміни. Контейнер, який запускається та постійно завершує роботу, перезапускається лише за наявності відповідної restart policy. Перевірте журнали, щоб визначити причину.docker image lsпоказує стовпець CREATED. Також перевірте вивід збірки та ID розгорнутого image, оскільки сам timestamp створення не підтверджує, що повторна збірка відбулася.
Якщо ви ще формуєте файл, до якого застосовуються ці перевірки, у матеріалі основи Compose-файлу на VPS описано пов’язані ключі, а в шпаргалці команд Compose наведено решту subcommands.
FAQ
Чи можна використовувати build і image в одному service?
Так. Це стандартна конфігурація для проєкту, який ви збираєте самостійно. Коли Compose збирає образ із секції build:, він позначає результат значенням image:. Якщо явно не вказати pull_policy, up спочатку намагається завантажити образ. Саме цей тег docker compose push надсилає до registry, а інша машина завантажує його. Якщо не вказати ключ image:, Compose все одно збирає образ, але називає його за іменами проєкту та service. Також він попереджає, що відсутній атрибут не дає змоги передати образ до registry.
Чому docker compose up не враховує зміни в Dockerfile?
Тому що звичайний up повторно використовує наявний образ, якщо явно не запросити збірку або не налаштувати політику, яка її вимагає. Команда не порівнює цей образ із Dockerfile або файлами вихідного коду, щоб визначити потребу в повторній збірці. Виконайте docker compose up -d --build або виконайте docker compose build web, а потім docker compose up --no-deps -d web, щоб замінити один service. Якщо задати pull_policy: build для service, кожен up виконуватиме повторну збірку. Це зручно на машині для розробки.
У чому різниця між --build і --force-recreate?
--build повторно збирає образ, а потім повторно створює контейнери, образ яких змінився. --force-recreate примусово повторно створює контейнери, навіть якщо конфігурація та образ не змінилися. Ця опція сама по собі не запускає збірку. Якщо зміни внесено у вихідний код або Dockerfile, потрібна опція --build. --force-recreate призначена для повторного створення самого контейнера, наприклад щоб очистити його шар із правом запису, зберігши той самий образ.
Чи слід збирати Docker images на VPS чи в іншому місці?
Збирайте образи в іншому місці та завантажуйте тег на сервер, який уже обслуговує network traffic. Збірка конкурує із застосунком за memory. У разі вичерпання memory kernel вибирає процес для завершення за допомогою змінюваного OOM score. Цим процесом може стати збірка або ваша database. Збірки також залишають cache на диску, хоча BuildKit автоматично очищає його відповідно до політик garbage collection. Збірка на сервері підходить для невеликого проєкту без користувачів. Пізніше перенесення не потребує значних зусиль, якщо зберігати секцію build: в окремому Compose-файлі лише для розробки.
Як запобігти заповненню диска Docker build cache?
Виконайте docker system df, щоб перевірити, скільки місця займають images і build cache. docker builder prune видаляє кешовані шари, а docker image prune — dangling images, які залишилися після попередніх збірок. Додавання -a видаляє весь невикористаний build cache або всі images, на які не посилаються контейнери, відповідно. Це не гарантує повністю «холодну» наступну збірку. Не плануйте виконання docker system prune -af --volumes на сервері, оскільки команда видаляє зупинені контейнери та невикористовувані anonymous volumes. Через це дані database в anonymous volume можуть бути втрачені під час обслуговування.