SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

Docker Compose: تفاوت build و image روی VPS چیست؟

image یک image آماده را انتخاب می‌کند و build آن را می‌سازد. ببینید چرا compose up تغییر Dockerfile را نادیده می‌گیرد و چگونه با build اجباری رفعش کنید.

Docker Compose در برابر image: پاسخ کوتاه

در فایل Docker Compose، image:، image مورد استفاده را مشخص می‌کند؛ این image می‌تواند یک image محلی، یک tag یا یک digest reference باشد. build: به Compose می‌گوید چگونه آن را از source بسازد. فقط image: را تنظیم کنید تا Compose، image را مطابق pull_policy استفاده کند یا pull کند. فقط build: را تنظیم کنید تا Compose با builder پیکربندی‌شده image را بسازد و نامی مشتق‌شده از نام project و نام service به آن اختصاص دهد. اگر هر دو را تنظیم کنید، pull_policy مشخص می‌کند که Compose image را pull کند یا بسازد. هنگام build، نتیجه با نام موجود در image: tag می‌شود؛ به این ترتیب می‌توانید image را بسازید و آن را با نامی که انتخاب کرده‌اید push کنید. builder می‌تواند به‌صورت local یا روی یک Docker host راه دور اجرا شود.

این تمام تفاوت است. مطالب زیر توضیح می‌دهند که این تفاوت در عمل روی یک server چه معنایی دارد. فرض بر این است که Docker Engine و Compose plugin از قبل نصب شده‌اند؛ اجرای Docker روی یک VPS این بخش را پوشش می‌دهد.

سه شکل کامل

از یک tag منتشرشده استفاده می‌کند و در صورت نبودن آن، طبق pull policy پیش‌فرض آن را دریافت می‌کند. در هیچ مرحله‌ای Dockerfile درگیر نیست.

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

از Dockerfile موجود در directory پروژه build می‌کند. این build می‌تواند imageها را نیز دریافت کند و dependencyهای موردنیاز Dockerfile را download کند.

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

نتیجه را با docker compose build build و tag می‌کند؛ اگر pull policy به‌صراحت تعیین نشده باشد، up پیش از build کردن این image، تلاش می‌کند آن را pull کند. سپس 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 directoryای است که به builder ارسال می‌شود. dockerfile نسبت به این context resolve می‌شود؛ بنابراین استفاده از context: . همراه با dockerfile: docker/prod.Dockerfile معمول و صحیح است. برای مشاهده نام image و image ID مربوط به هر service container، docker compose images را اجرا کنید؛ فایل Compose را بررسی کنید تا مشخص شود service از image:، build: یا هر دو استفاده می‌کند.

چرا docker compose up پس از تغییر Dockerfile دوباره build انجام نمی‌دهد؟

زیرا `up` معمولی از image موجود دوباره استفاده می‌کند، مگر آن‌که build را درخواست کنید یا policyای تنظیم کنید که build را الزامی کند.

وقتی Compose سرویسی را اجرا می‌کند که فقط بخش `build: را دارد، اگر image موجود باشد از همان استفاده می‌کند. Compose Dockerfile شما را نمی‌خواند، فایل‌های source را مقایسه نمی‌کند و timestampها را نیز بررسی نمی‌کند. اگر image: و build: هر دو وجود داشته باشند و pull_policy` به‌طور صریح مشخص نشده باشد، Compose ابتدا pull را امتحان می‌کند و اگر image در registry یا platform cache موجود نباشد، build انجام می‌دهد. موجود بودن image کافی تلقی می‌شود.

بنابراین `app.py را ویرایش می‌کنید، docker compose up -d` را اجرا می‌کنید، می‌بینید Compose گزارش می‌دهد container در حال اجرا است، اما کد قدیمی ارائه می‌شود. هیچ خطایی رخ نداده است؛ بنابراین هشداری نیز دریافت نمی‌کنید. نشانه اصلی، status wordای است که Compose کنار نام container چاپ می‌کند: برای containerای که Compose آن را جایگزین کرده است، status به‌صورت recreated یا started گزارش می‌شود و برای containerای که Compose تصمیم گرفته دست‌نخورده باقی بگذارد، status به‌صورت running نمایش داده می‌شود.

دو بررسی موضوع را مشخص می‌کنند. `docker compose images، image ID مورد استفاده هر container را چاپ می‌کند؛ بنابراین آن را پیش از deploy یادداشت و پس از آن مقایسه کنید. docker image ls` ستونی با نام CREATED دارد، اما buildهای cacheشده و timestampهای reproducible باعث می‌شوند این تاریخ به‌تنهایی ثابت نکند که آخرین source شما build شده است.

کدام flagها بازسازی را اجباری می‌کنند

  • docker compose up -d --build ابتدا build را انجام می‌دهد و سپس هر containerای را که image آن تغییر کرده است، دوباره ایجاد می‌کند. این همان flagی است که بیشتر کاربران به دنبال آن هستند.
  • docker compose build web فقط یک service را build می‌کند و هیچ‌چیز را start نمی‌کند. آن را با docker compose up --no-deps -d web دنبال کنید تا فقط همان container جایگزین شود و بقیه stack همچنان در حال اجرا بماند.
  • docker compose build --no-cache web لایه‌های cache‌شده را نادیده می‌گیرد و service را دوباره build می‌کند.
  • docker compose build --pull تلاش می‌کند نسخه جدیدتری از base image را در FROM pull کند؛ بنابراین یک tag متغیر مانند node:22 به‌جای نسخه‌ای که در ماه March دانلود کرده‌اید، محتوای فعلی خود را دریافت می‌کند.
  • docker compose up -d --force-recreate حتی زمانی که configuration و image تغییر نکرده‌اند، ایجاد دوباره container را اجباری می‌کند. این flag به‌تنهایی build را درخواست نمی‌کند، اما up همچنان می‌تواند زمانی build را انجام دهد که image موجود نباشد یا pull policy به آن نیاز داشته باشد. استفاده از این گزینه زمانی که منظور شما --build بوده است، یک بن‌بست رایج است.

می‌توانید این تصمیم را نیز در فایل قرار دهید. طبق توضیح Compose specification، pull_policy: build یعنی Compose image را build می‌کند و اگر image از قبل وجود داشته باشد، آن را دوباره build می‌کند. در نتیجه، هر up هزینه یک build را به همراه دارد؛ این رفتار روی laptop مطلوب است، اما روی server به‌ندرت مطلوب خواهد بود.

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

یک تعامل دیگر نیز ارزش دانستن دارد. docker compose pull تلاش می‌کند imageهای serviceهایی را که بخش build دارند نیز pull کند و اگر این pull شکست بخورد، اعلام می‌کند که image باید build شود. برای نادیده گرفتن بی‌سروصدای این serviceها، --ignore-buildable را ارسال کنید.

تصمیم cache ساخت درباره زمان deploy شما

builder هر دستور Dockerfile را بررسی می‌کند تا اگر آن دستور و ورودی‌هایش تغییر نکرده‌اند، نتیجه cache‌شده و قابل‌استفاده مجدد را پیدا کند. برای COPY، ورودی‌ها شامل محتوای فایل‌ها و metadata آن‌ها هستند، اما زمان‌های تغییر را شامل نمی‌شوند. به‌محض آن‌که یکی از layerها cache را از دست بدهد، مراحل بعدی که به آن وابسته‌اند دوباره build می‌شوند.

همین یک قاعده تعیین می‌کند deploy شما چند ثانیه یا چند دقیقه طول بکشد. 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 . . قرار دارد؛ بنابراین ویرایش یک فایل source باعث می‌شود install layer در cache باقی بماند و build از مرحله copy ادامه پیدا کند. اگر این دو خط را جابه‌جا کنید، یک تغییر یک‌کاراکتری همه dependencyها را دوباره نصب می‌کند، چون COPY . . لایه‌ای را نامعتبر می‌کند که npm ci بر پایه آن ساخته شده است. همین الگو برای pip install -r requirements.txt و go mod download نیز صدق می‌کند.

--no-cache زمانی ابزار مناسبی است که احتمال می‌دهید یک layer قدیمی اصلاح شما را پنهان کرده باشد. استفاده از آن به‌عنوان مقدار پیش‌فرض مناسب نیست، چون reuseای را از بین می‌برد که هدف مرتب‌سازی Dockerfile ایجاد آن است.

یک مورد را image sets می‌کند و Compose می‌تواند آن را override کند: CMD در Dockerfile تعیین می‌کند image به‌طور پیش‌فرض چه چیزی را اجرا کند، و کلید command: در service جایگزین آن می‌شود. نحوه تعامل command و entrypoint در اینجا اهمیت دارد، زیرا یک override در Compose می‌تواند باعث شود image تازه buildشده دقیقاً مانند image قدیمی رفتار کند.

زمینهٔ ساخت و .dockerignore

context: . دایرکتوری پروژه را در اختیار builder قرار می‌دهد. بدون exclusion، این فرایند شامل .git و هر data directory دیگری نیز می‌شود که در کنار source نگه می‌دارید؛ هرچند BuildKit فایل‌های استفاده‌نشده را نادیده می‌گیرد و تغییرات را به‌صورت incremental منتقل می‌کند. اگر build در مرحلهٔ transferring-context برای پروژه‌ای که در آن تغییری ایجاد نشده است متوقف می‌شود، این وضعیت نشان می‌دهد که context بیش از حد بزرگ است.

یک فایل .dockerignore در ریشهٔ context، مسیرها را از این انتقال حذف می‌کند. syntax آن به .gitignore نزدیک است.

.git
node_modules
*.log
data/
.env

این کار دو مزیت دارد. نخست، حجم انتقال کمتر می‌شود و زمان صرف‌شده برای ارسال این فایل‌ها کاهش می‌یابد. دوم، COPY . . دیگر نمی‌تواند .env را داخل image کپی کند؛ در نتیجه هر کسی که آن image را pull کند، نمی‌تواند محتوای آن را بخواند.

موردی که باعث کندترشدن تدریجی build می‌شود، bind mount است. یک named volume خارج از دایرکتوری پروژه قرار دارد، اما bind mount مانند ./data:/var/lib/postgresql/data داخل build context قرار می‌گیرد؛ بنابراین هر هفته، هم‌زمان با بزرگ‌ترشدن database، buildهای شما کندتر می‌شوند. یک خط در .dockerignore این مشکل را برطرف می‌کند. بخش bind mount در برابر named volume trade-off گسترده‌تر این انتخاب را توضیح می‌دهد.

Build argumentها نسخهٔ محدودتری از همین ریسک را ایجاد می‌کنند. مقادیری که از طریق args: ارسال می‌شوند، ممکن است در image history یا provenance metadata باقی بمانند؛ بنابراین در آن‌جا یک version number قرار دهید و هرگز token قرار ندهید. predefined proxy argumentها، مگر آن‌که صراحتاً در Dockerfile به آن‌ها ارجاع داده شود، به‌طور پیش‌فرض از build cache و docker history مستثنا هستند. بخش فایل‌های Env و secretها در Compose توضیح می‌دهد که credentialها باید در کجا قرار بگیرند.

آیا باید روی VPS build کنید یا build را در جای دیگری انجام دهید و pull کنید؟

build روی سروری که traffic شما را ارائه می‌کند، انتخاب پیش‌فرض است؛ چون کوتاه‌ترین مسیر را دارد: git pull و سپس docker compose up -d --build. این روش برای یک سرور کوچک که هنوز سرویس مهمی به آن وابسته نیست، مناسب است. اما به دو دلیل قابل‌اندازه‌گیری و یک دلیل دیگر که فقط در روزهای مشکل‌ساز آشکار می‌شود، دیگر مناسب نخواهد بود.

حافظه. یک build، compilerها و bundlerها را در کنار application فعال شما اجرا می‌کند و این‌ها در بیشتر stackها بیشترین حافظه را مصرف می‌کنند. یک JavaScript bundler یا build مربوط به Rust می‌تواند حافظه موجود در یک VPS با 1 GB را تمام کند. هنگام تمام‌شدن حافظه، kernel با استفاده از امتیاز badness، که بر اساس میزان مصرف حافظه، context تخصیص و oom_score_adj محاسبه می‌شود، یک فرایند را به‌عنوان OOM victim انتخاب می‌کند؛ kernel صرفاً بزرگ‌ترین فرایند را متوقف نمی‌کند. build ممکن است با Killed و exit status برابر با 137 متوقف شود، یا database شما به‌جای آن متوقف شود و سایت در میانه deploy از دسترس خارج شود. dmesg -T | grep -i oom لاگ kernel را برای پیام‌های OOM جست‌وجو می‌کند؛ اجرای آن به مجوز خواندن این لاگ نیاز دارد.

دیسک. buildها image layerها و build cache را باقی می‌گذارند. docker system df میزان مصرف دیسک آن‌ها را نشان می‌دهد؛ garbage collection دوره‌ای BuildKit، cache را بر اساس policyهای پیکربندی‌شده پس می‌گیرد. برای imageهای dangling از docker image prune و برای layerهای cache‌شده از docker builder prune استفاده کنید. پرشدن دیسک فقط build را متوقف نمی‌کند. database نیز دیگر نمی‌تواند بنویسد و این خرابی هزینه‌ای بسیار بیشتر از یک deploy کند دارد.

تکرارپذیری. اگر image را push یا export نکنید، image ساخته‌شده روی سرور فقط روی همان سرور وجود دارد. اگر image قدیمی دیگر در دسترس نباشد، rollback به این معناست که commit قدیمی را checkout کنید و دوباره build بگیرید؛ اما تضمینی وجود ندارد که این build همان خروجی قبلی را تولید کند، چون base tag تغییر کرده و package mirrorها نیز همراه آن تغییر کرده‌اند. build در جای دیگر و push کردن یک tag، rollback را به یک ویرایش ساده تبدیل می‌کند: image: را روی tag قبلی قرار دهید و docker compose up -d را اجرا کنید.

چیدمانی که در عمل پایدار می‌ماند، ساده است. continuous integration شما build را اجرا می‌کند و registry.example.com/acme/web:<git-sha> را push می‌کند؛ سپس فایل Compose روی VPS، image: را بدون هیچ کلید build: در اختیار دارد. در این حالت، deployment فقط دو command است و تقریباً به حافظه‌ای نیاز ندارد.

docker compose pull
docker compose up -d

برای ذخیره credentialهای لازم جهت pull کردن tagهای خصوصی، docker login registry.example.com را روی سرور اجرا کنید.

بخش build را برای development نگه دارید و آن را حذف نکنید؛ این بخش را در فایلی قرار دهید که خودتان نام‌گذاری می‌کنید.

# 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 file وجود داشته باشد، آن را به‌طور خودکار بارگذاری می‌کند؛ بنابراین اگر یک override سرگردان روی سرور کپی شود، build دوباره و بدون جلب توجه روی همان سرور شروع خواهد شد. لایه‌بندی چند فایل Compose توضیح می‌دهد که merge برای هر کلید چگونه resolve می‌شود.

دام معماری هنگام ساخت در محیطی دیگر

هر image پلتفرم، معماری CPUای را در خود دارد که برای آن ساخته شده است. اگر یک image مبتنی بر ARM را روی لپ‌تاپ Apple Silicon بسازید، آن را push کنید و سپس در یک VPS مبتنی بر x86_64 استفاده کنید، Docker هنگام ایجاد container هشدار می‌دهد؛ این وضعیت زمانی رخ می‌دهد که Docker بدون تعیین صریح platform از یک image ناسازگارِ cache‌شده استفاده کند. بدون emulation، فرایند با exec format error شکست می‌خورد. این پیام شبیه خطای binary خراب است، اما binary خراب نیست. معماری مقصد را صریحاً تعیین کنید:

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

اگر لپ‌تاپ شما x86 باشد و آن را روی یک VPS مبتنی بر ARM، نه x86 اجرا کنید، همین ناسازگاری در جهت معکوس رخ می‌دهد. اگر ساخت image را به CI بسپارید و آن را روی معماری مقصد انجام دهید، این مسئله برطرف می‌شود. یک image چندپلتفرمی نیز همین مشکل را حل می‌کند: Docker هنگام pull کردن image، variant سازگار را انتخاب می‌کند.

پس از deploy چه چیزهایی را بررسی کنیم

  • docker compose images، image و tag مربوط به هر container در حال اجرا را نمایش می‌دهد. تغییر image ID نشان می‌دهد که build جدید در حال سرویس‌دهی است.
  • docker compose config، فایل ادغام‌شده را پس از جایگزینی متغیرها نمایش می‌دهد تا پیش از اجرای هر چیزی، نام نهایی image مورد استفادهٔ Compose را ببینید.
  • docker compose logs -f web، در 30 ثانیهٔ نخست پس از جابه‌جایی آن را monitor کنید. containerی که مرتب start می‌شود و خارج می‌شود، فقط در صورتی دوباره restart می‌شود که restart policy آن چنین رفتاری را مشخص کرده باشد؛ علت را در لاگ‌ها بررسی کنید.
  • docker image ls، ستون CREATED را نمایش می‌دهد. خروجی build و image ID مربوط به deploy را نیز بررسی کنید، زیرا timestamp ایجاد به‌تنهایی نشان نمی‌دهد که rebuild اجرا شده است.

اگر هنوز در حال آماده‌سازی فایلی هستید که این بررسی‌ها روی آن اجرا می‌شوند، مبانی فایل Compose در یک VPS کلیدهای مرتبط را توضیح می‌دهد و راهنمای سریع commandهای Compose بقیهٔ subcommandها را فهرست می‌کند.

FAQ

آیا می‌توانم از build و image در یک service استفاده کنم؟

بله. این حالت برای پروژه‌ای که خودتان می‌سازید، پیکربندی معمول است. وقتی Compose از بخش build: build می‌کند، نتیجه را با مقدار image: tag می‌کند؛ اگر pull_policy به‌صراحت تعیین نشده باشد، up ابتدا تلاش می‌کند image را pull کند. همین tag است که docker compose push به registry ارسال می‌کند و ماشین دیگر آن را pull می‌کند. اگر کلید image: وجود نداشته باشد، Compose همچنان build را انجام می‌دهد، اما نام image را بر اساس project و service تعیین می‌کند و هشدار می‌دهد که نبودن این attribute مانع push شدن image می‌شود.

چرا docker compose up تغییر Dockerfile من را اعمال نمی‌کند؟

زیرا up معمولی از image موجود دوباره استفاده می‌کند، مگر آن‌که build را درخواست کنید یا policyای تنظیم کنید که build را الزامی کند. این دستور image را با Dockerfile یا فایل‌های source مقایسه نمی‌کند تا مشخص شود آیا rebuild لازم است یا نه. docker compose up -d --build را اجرا کنید، یا برای جایگزین کردن یک service، docker compose build web را اجرا کنید و سپس docker compose up --no-deps -d web را اجرا کنید. تنظیم pull_policy: build روی service باعث می‌شود هر up عملیات rebuild را انجام دهد؛ این حالت برای یک ماشین development مناسب است.

تفاوت --build و --force-recreate چیست؟

--build image را دوباره build می‌کند و سپس containerهایی را که image آن‌ها تغییر کرده است، دوباره ایجاد می‌کند. --force-recreate حتی زمانی که configuration و image تغییر نکرده‌اند، containerها را مجبور به recreate شدن می‌کند؛ این گزینه به‌تنهایی build را درخواست نمی‌کند. اگر تغییر شما در source یا Dockerfile است، --build همان flag موردنیاز شماست. --force-recreate برای reset کردن خود container استفاده می‌شود؛ مثلاً برای پاک کردن writable layer آن، در حالی که همان image حفظ می‌شود.

آیا باید Docker imageهای خود را روی VPS build کنم یا در جای دیگری؟

وقتی سرور شما هم‌زمان network traffic سرویس می‌دهد، image را در جای دیگری build کنید و پس از آن tag را pull کنید. عملیات build برای memory با برنامه شما رقابت می‌کند و هنگام اتمام memory، kernel با استفاده از OOM score قابل‌تنظیم، یکی از فرایندها را به‌عنوان قربانی انتخاب می‌کند؛ این فرایند ممکن است build یا database شما باشد. عملیات build همچنین روی disk cache باقی می‌گذارد، هرچند BuildKit طبق policyهای garbage collection خود آن را به‌صورت خودکار reclaim می‌کند. برای یک پروژه کوچک بدون user، build کردن روی server همچنان مناسب است. اگر بخش build: را در یک Compose file مخصوص development نگه دارید، انتقال این فرایند در آینده هزینه زیادی نخواهد داشت.

چگونه از پر شدن disk با Docker build cache جلوگیری کنم؟

docker system df را اجرا کنید تا ببینید imageها و build cache شما هرکدام چه مقدار فضا اشغال کرده‌اند. docker builder prune لایه‌های cacheشده را حذف می‌کند و docker image prune imageهای dangling باقی‌مانده از buildهای قبلی را حذف می‌کند. افزودن -a به‌ترتیب همه build cacheهای استفاده‌نشده یا همه imageهای بدون reference از سوی containerها را حذف می‌کند؛ اما cold بودن کامل build بعدی را تضمین نمی‌کند. docker system prune -af --volumes را روی server زمان‌بندی نکنید، زیرا containerهای متوقف‌شده و anonymous volumeهای استفاده‌نشده را حذف می‌کند و در نتیجه داده‌های database موجود در یک anonymous volume ممکن است هنگام maintenance در معرض خطر قرار بگیرند.

آیا این مقاله مفید بود؟