'\" t .nh .TH "CONTAINERFILE" "5" "اوت ۲۰۲۱" "" "راهنمای کاربری کانتینر" .SH "نام (NAME)" Containerfile \- خودکارسازی مراحل ایجاد و ساخت تصویر کانتینر (Dockerfile) .SH "مقدمه (INTRODUCTION)" پرونده \fBContainerfile\fP یک فایل پیکربندی است که مراحل ایجاد تصویر کانتینر را خودکار می‌کند. این فایل عملکردی مشابه یک Makefile دارد. موتورهای کانتینر (Podman، Buildah، Docker) دستورالعمل‌های موجود در \fBContainerfile\fP را می‌خوانند تا مراحلی را که در غیر این صورت باید دستی انجام می‌شد، برای ساخت تصویر خودکار سازند. برای ساخت یک تصویر، فایلی به نام \fBContainerfile\fP بسازید. .PP پرونده \fBContainerfile\fP مراحل طی‌شده برای سرهم‌بندی تصویر را شرح می‌دهد. هنگامی که \fBContainerfile\fP ایجاد شد، دستورات \fBbuildah build\fR، \fBpodman build\fR یا \fBdocker build\fR را فراخوانی کنید و مسیر دایرکتوری زمینه حاوی \fBContainerfile\fP را به عنوان آرگومان به آن بدهید. ابزارهای Podman و Buildah به طور پیش‌فرض از \fBContainerfile\fP استفاده می‌کنند و در صورت عدم وجود به \fBDockerfile\fP رجوع می‌نمایند. موتور داکر تنها به دنبال \fBDockerfile\fP در دایرکتوری زمینه می‌گردد. .PP نام \fBDockerfile\fP نامی جایگزین برای همین فایل است. هر دو فایل \fBContainerfile\fP و \fBDockerfile\fP از ساختار و دستورات یکسانی پشتیبانی می‌کنند. .SH "خلاصه دستور (SYNOPSIS)" INSTRUCTION arguments .PP برای نمونه: .PP FROM image .SH "توضیحات (DESCRIPTION)" یک Containerfile فایلی است که مراحل ایجاد یک تصویر کانتینر را خودکارسازی می‌کند. یک Containerfile ساختاری مشابه یک Makefile دارد. .SH "نحوه استفاده (USAGE)" .EX buildah build . podman build . .EE .PP -- مراحل را اجرا کرده و نتایج را تثبیت (commit) می‌کند تا تصویر نهایی ساخته شود. مسیر منتهی به مخزن منبع مشخص می‌کند که زمینه ساخت در کجا یافت شود. .EX buildah build -t repository/tag . podman build -t repository/tag . .EE .PP -- در صورت موفقیت‌آمیز بودن ساخت، مخزن و برچسبی (tag) را که تصویر جدید در آن ذخیره می‌شود مشخص می‌کند. موتور کانتینر مراحل را گام‌به‌گام اجرا کرده و در صورت نیاز نتیجه را در یک تصویر جدید ثبت می‌کند، تا در نهایت شناسه (ID) تصویر جدید را ارائه دهد. .PP موتورهای کانتینر تا جای ممکن تصاویر میانی را مجدداً استفاده می‌کنند. این امر فرآیند \fIساخت\fP را به شکل چشمگیری سریع‌تر می‌کند. .SH "قالب دستورات (FORMAT)" \fBFROM image [AS ]\fR .PP \fBFROM image:tag [AS ]\fR .PP \fBFROM image@digest [AS ]\fR .PP -- دستورالعمل \fBFROM\fP تصویر پایه را برای دستورالعمل‌های پس از خود تعیین می‌کند. یک Containerfile معتبر باید \fBARG\fP یا \fBFROM\fP را به عنوان نخستین دستورالعمل خود داشته باشد. اگر \fBFROM\fP نخستین دستورالعمل در فایل نباشد، تنها می‌تواند پس از یک یا چند دستورالعمل ARG بیاید که آرگومان‌های مورد استفاده در خط بعدی FROM را اعلان می‌کنند. تصویر پایه می‌تواند هر تصویر معتبری باشد. ساده‌ترین راه شروع، دریافت یک تصویر از مخازن عمومی است. .PP -- دستورالعمل \fBFROM\fP باید دست‌کم یک بار در Containerfile درج شود. .PP -- نخستین دستور \fBFROM\fP باید پیش از تمام دستورالعمل‌های دیگر موجود در Containerfile به جز \fBARG\fP بیاید. .PP -- دستورالعمل \fBFROM\fP می‌تواند چندین بار درون یک Containerfile تکرار شود تا چند تصویر ساخته شود. شناسه آخرین تصویری را که توسط commit پیش از هر دستور جدید \fBFROM\fP تولید می‌شود ثبت نمایید. .PP -- اگر هیچ تگی به دستورالعمل \fBFROM\fP داده نشود، موتورهای کانتینر برچسب \fBlatest\fR را اعمال می‌کنند. در صورتی که برچسب استفاده‌شده وجود نداشته باشد، خطا برگردانده می‌شود. .PP -- اگر هیچ شناسه دایجستی به دستورالعمل \fBFROM\fP داده نشود، موتورهای کانتینر برچسب \fBlatest\fR را اعمال می‌کنند. اگر برچسب استفاده‌شده وجود نداشته باشد، یک خطا بازگردانده می‌شود. .PP -- می‌توان با افزودن \fBAS name\fP به دستورالعمل، نامی به مرحله ساخت اختصاص داد. از این نام می‌توان بعداً در Containerfile با استفاده از دستورالعمل‌های \fBFROM\fP یا \fBCOPY --from=\fP ارجاع داد. .PP \fBMAINTAINER\fP -- دستورالعمل \fBMAINTAINER\fP فیلد Author (نویسنده/نگه‌دارنده) را برای تصاویر تولیدشده تعیین می‌کند. این گزینه برای ارائه ایمیل یا آدرس اینترنتی پشتیبانی به کاربران کاربرد دارد. .PP \fBRUN\fP -- دستورالعمل \fBRUN\fP دو قالب دارد: .EX # the command is run in a shell - /bin/sh -c RUN # Executable form RUN ["executable", "param1", "param2"] .EE .PP \fBRUN mounts\fP .PP \fB--mount\fP=\fItype=TYPE,TYPE-SPECIFIC-OPTION[,...]\fP .PP اتصال یک مانت سیستم‌فایل به کانتینر .PP انواع در حال حاضر پشتیبانی‌شده برای mount عبارتند از bind، cache، secret و tmpfs. .EX e.g. mount=type=bind,source=/path/on/host,destination=/path/in/container,relabel=shared mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container mount=type=secret,id=mysecret cat /run/secrets/mysecret Common Options: · src, source: مشخص کردن منبع مانت برای bind و volume. برای bind الزامی است. · dst, destination, target: مشخص کردن مقصد مانت. · ro, read-only: فقط‌خواندنی: true (پیش‌فرض) یا false. Options specific to bind: · bind-propagation: مقادیر shared, slave, private, rshared, rslave یا rprivate (پیش‌فرض). · bind-nonrecursive: عدم راه‌اندازی مانت بایندی بازگشتی (به‌طور پیش‌فرض بازگشتی است). · from: نام مرحله یا تصویر برای ریشه منبع. پیش‌فرض زمینه ساخت است. · relabel=shared, z: برچسب‌گذاری مجدد محتوای src با برچسب مشترک (shared). · relabel=private, Z: برچسب‌گذاری مجدد محتوای src با برچسب خصوصی (private). سیستم‌های برچسب‌گذاری مانند SELinux نیاز به برچسب‌های مناسب روی محتوای متصل‌شده دارند. گزینه relabel=shared و z نشان می‌دهد که دو یا چند کانتینر محتوا را به اشتراک می‌گذارند. گزینه relabel=private و Z نشان می‌دهد که تنها کانتینر جاری از مانت استفاده می‌کند. · rw, read-write: اجازه نوشتن روی مانت. Options specific to tmpfs: · tmpfs-size: اندازه مانت tmpfs به بایت (نامحدود در لینوکس به طور پیش‌فرض). · tmpfs-mode: حالت مجوز فایل در فرمت هشت‌هشتی (مانند 700 یا 0700، پیش‌فرض 1777). · tmpcopyup: مسیری که زیر tmpfs قرار می‌گیرد به درون خود tmpfs کپی می‌شود. Options specific to cache: · id: ایجاد یک دایرکتوری کش جداگانه برای یک شناسه خاص. · mode: حالت دسترسی برای دایرکتوری کش به صورت هشت‌هشتی (پیش‌فرض 0755). · ro, readonly: کش فقط‌خواندنی در صورت تنظیم. · uid: شناسه کاربر برای دایرکتوری کش. · gid: شناسه گروه برای دایرکتوری کش. · from: نام مرحله برای ریشه منبع (پیش‌فرض دایرکتوری کش میزبان). · rw, read-write: مجاز شمردن نوشتن روی مانت کش. .EE .PP \fBRUN --network\fP .PP گزینه \fBRUN --network\fR امکان کنترل این را فراهم می‌کند که دستور در کدام محیط شبکه اجرا شود. .PP قالب دستور: \fB--network=\fR .PP \fBانواع شبکه\fP .TS allbox; l l l l . \fBنوع (Type)\fP \fBتوضیحات (Description)\fP \[la]#run\-\-\-networkdefault\[ra] (پیش‌فرض) اجرا در شبکه پیش‌فرض. \[la]#run\-\-\-networknone\[ra] اجرا بدون دسترسی به شبکه. \[la]#run\-\-\-networkhost\[ra] T{ اجرا در محیط شبکه میزبان. T} .TE .SS RUN --network=default معادل با عدم ارائه هیچ فلگی است، و دستور در شبکه پیش‌فرض ساخت اجرا می‌شود. .SS RUN --network=none دستور بدون دسترسی به شبکه اجرا می‌شود (رابط \fBlo\fR همچنان در دسترس است، اما منحصر به این فرآیند خواهد بود). .SS مثال: جداسازی اثرات خارجی .EX FROM python:3.6 ADD mypackage.tgz wheels/ RUN --network=none pip install --find-links wheels mypackage .EE .PP ابزار \fBpip\fR تنها قادر خواهد بود بسته‌های ارائه‌شده در فایل tar را نصب کند، که می‌توان آن را توسط یک مرحله ساخت قبلی کنترل کرد. .SS RUN --network=host دستور در محیط شبکه میزبان اجرا می‌شود (مشابه \fBbuildah build --network=host\fR، اما برای هر دستورالعمل به صورت جداگانه). .PP \fBاسرار RUN (Secrets)\fP .PP دستور RUN قابلیتی برای انتقال اطلاعات محرمانه (رازها) به فرآیند ساخت تصویر دارد. این فایل‌های محرمانه می‌توانند در طول اجرای دستور RUN استفاده شوند، اما در تصویر نهایی ذخیره (commit) نمی‌شوند. دستور \fBRUN\fR از گزینه \fB--mount\fR برای شناسایی فایل محرمانه پشتیبانی می‌کند. یک فایل محرمانه از میزبان در حین ساخته شدن تصویر به درون کانتینر متصل (مانت) می‌شود. .PP موتورهای کانتینر فایل محرمانه را با استفاده از فلگ \fB--secret\fR به فرآیند ساخت ارسال می‌کنند. .PP \fB--mount\fP=\fItype=secret,TYPE-SPECIFIC-OPTION[,...]\fP .IP \(bu 2 شناسه \fBid\fR همان شناسه فایل محرمانه‌ای است که به دستور \fBbuildah build --secret\fR یا \fBpodman build --secret\fR ارسال شده است. این شناسه با شناسه RUN --mount در Containerfile پیوند می‌خورد. .IP \(bu 2 گزینه‌های \fBdst\fR|\fBtarget\fR|\fBdestination\fR نام فایل محرمانه را به یک فایل مشخص در دستور RUN کانتینرفایل تغییر می‌دهند تا استفاده شود. .IP \(bu 2 مقدار \fBtype=secret\fR به دستور --mount اعلام می‌کند که در حال اتصال یک فایل محرمانه است. .EX # نمایش راز از مسیر پیش‌فرض راز: RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret .EE .EX # نمایش راز از مسیر سفارشی راز: RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar .EE .PP راز باید با استفاده از فلگ --secret به ساخت ارسال شود. تصویر نهایی ساخته‌شده حاوی این فایل محرمانه نخواهد بود: .EX buildah build --no-cache --secret id=mysecret,src=mysecret.txt . .EE .PP -- دستورالعمل \fBRUN\fP هر دستوری را در یک لایه جدید بر روی تصویر فعلی اجرا کرده و نتایج را ثبت (commit) می‌کند. تصویر ثبت‌شده برای مرحله بعدی در Containerfile به کار می‌رود. .PP -- لایه‌بندی دستورالعمل‌های \fBRUN\fP و ایجاد commit با مفاهیم اصلی موتورهای کانتینر مطابقت دارد؛ جایی که commitها کم‌هزینه هستند و می‌توان کانتینرها را از هر نقطه‌ای از تاریخچه یک تصویر ایجاد کرد. این کار شبیه به سیستم‌های کنترل نسخه است. فرم اجرایی (exec form) از دستکاری رشته‌های شل جلوگیری می‌کند و امکان اجرای دستورات \fBRUN\fP را با استفاده از یک تصویر پایه که حاوی \fB/bin/sh\fR نیست فراهم می‌سازد. .PP توجه داشته باشید که فرم exec به صورت یک آرایه JSON تفسیر می‌شود، به این معنی که باید در اطراف کلمات از علامت نقل‌قول دوتایی (") استفاده کنید، نه علامت نقل‌قول تکی ('). .PP \fBCMD\fP -- دستورالعمل \fBCMD\fP دارای سه قالب است: .EX # Executable form CMD ["executable", "param1", "param2"]` # Provide default arguments to ENTRYPOINT CMD ["param1", "param2"]` # the command is run in a shell - /bin/sh -c CMD command param1 param2 .EE .PP -- در هر Containerfile باید تنها یک دستورالعمل \fBCMD\fP وجود داشته باشد. اگر بیش از یک \fBCMD\fP درج شده باشد، تنها آخرین \fBCMD\fP اعمال خواهد شد. هدف اصلی \fBCMD\fP ارائه مقادیر پیش‌فرض برای اجرای کانتینر است. این پیش‌فرض‌ها می‌توانند شامل یک فایل اجرایی باشند، یا می‌توانند فایل اجرایی را حذف کنند. در صورتی که فایل اجرایی حذف شود، باید حتماً یک \fBENTRYPOINT\fP مشخص شده باشد. هنگامی که در قالب‌های shell یا exec استفاده می‌شود، دستورالعمل \fBCMD\fP دستوری را که باید هنگام اجرای تصویر اجرا شود تعیین می‌کند. اگر از حالت شل در \fBCMD\fP استفاده کنید، دستور \fB\fR در مسیر \fB/bin/sh -c\fR اجرا می‌شود: .PP توجه داشته باشید که حالت exec به صورت یک آرایه JSON تجزیه می‌شود، به این معنی که باید کلمات را با علامت نقل‌قول دوتایی (") محصور کنید، نه نقل‌قول تکی ('). .EX FROM ubuntu CMD echo "This is a test." | wc - .EE .PP -- اگر \fBcommand\fP را بدون شل اجرا می‌کنید، باید دستور را به عنوان یک آرایه JSON بیان کرده و مسیر کامل فایل اجرایی را ارائه دهید. این قالب آرایه‌ای، شکل توصیه‌شده \fBCMD\fP است. تمامی پارامترهای اضافی باید به صورت رشته‌های جداگانه در آرایه مشخص شوند: .EX FROM ubuntu CMD ["/usr/bin/wc","--help"] .EE .PP -- برای اینکه کانتینر هر بار یک فایل اجرایی مشخص را اجرا کند، از \fBENTRYPOINT\fP در ترکیب با \fBCMD\fP استفاده کنید. اگر کاربر آرگومان‌هایی را به \fBpodman run\fR یا \fBdocker run\fR ارائه دهد، دستورات مشخص‌شده جایگزین مقدار پیش‌فرض در \fBCMD\fP می‌شوند. دستور \fBRUN\fP را با \fBCMD\fP اشتباه نگیرید. دستور \fBRUN\fP یک دستور را در زمان ساخت اجرا کرده و نتیجه را ثبت می‌کند. دستور \fBCMD\fP در زمان ساخت چیزی را اجرا نمی‌کند، بلکه دستور پیش‌بینی‌شده برای زمان اجرای تصویر را مشخص می‌سازد. .PP \fBLABEL\fP -- \fBLABEL = [= ...]\fR یا .EX LABEL [ ] LABEL [ ] ... .EE .PP دستورالعمل \fBLABEL\fP متاداده را به تصویر اضافه می‌کند. یک \fBLABEL\fP جفتی از کلید-مقدار است. برای تعیین \fBLABEL\fP بدون مقدار، کافی است از یک رشته خالی استفاده کنید. برای گنجاندن فاصله‌ها در مقدار \fBLABEL\fP، مانند دستورات خط فرمان از نقل‌قول و بک‌اسلش استفاده نمایید. .EX LABEL com.example.vendor="ACME Incorporated" LABEL com.example.vendor "ACME Incorporated" LABEL com.example.vendor.is-beta "" LABEL com.example.vendor.is-beta= LABEL com.example.vendor.is-beta="" .EE .PP یک تصویر می‌تواند بیش از یک برچسب داشته باشد. برای تعیین چندین برچسب، هر جفت کلید-مقدار را با فاصله جدا کنید. .PP برچسب‌ها تجمعی هستند، از جمله برچسب‌های \fBLABEL\fR موجود در تصاویر \fBFROM\fR پایه. با مواجهه و اعمال هر برچسب جدید، \fBkey\fRهای جدید جایگزین برچسب‌های قبلی با کلیدهای یکسان می‌شوند. .PP برای نمایش برچسب‌های یک تصویر، از دستور \fBbuildah inspect\fR استفاده کنید. .PP \fBEXPOSE\fP -- \fBEXPOSE [...]\fR دستورالعمل \fBEXPOSE\fP به موتور کانتینر اعلام می‌کند که کانتینر در زمان اجرا به پورت‌های شبکه مشخص‌شده گوش می‌دهد. موتور کانتینر از این اطلاعات برای اتصال متقابل کانتینرها و راه‌اندازی تغییر مسیر پورت (port redirection) در سیستم میزبان استفاده می‌کند. .PP \fBENV\fP -- \fBENV \fR دستورالعمل \fBENV\fP متغیر محیطی را روی مقدار \fB\fR تنظیم می‌کند. این مقدار به تمامی دستورالعمل‌های \fBRUN\fP، \fBENTRYPOINT\fP و \fBCMD\fP بعدی منتقل می‌شود. این معادل با قرار دادن پیشوند \fB=\fR پیش از دستور است. متغیرهای محیطی تنظیم‌شده با \fBENV\fP هنگام اجرای کانتینر از تصویر نهایی پایدار باقی می‌مانند. برای مشاهده این مقادیر از \fBpodman inspect\fR استفاده کنید و برای تغییر آن‌ها از \fBpodman run --env =\fR بهره ببرید. .PP توجه داشته باشید که تنظیم "\fBENV DEBIAN_FRONTEND=noninteractive\fR" ممکن است پیامدهای ناخواسته‌ای داشته باشد، زیرا هنگام اجرای تعاملی کانتینر (مانند دستور \fBpodman run -t -i image bash\fR) نیز برقرار خواهد ماند. .PP \fBADD\fP -- دستورالعمل \fBADD\fP دو قالب دارد: .EX ADD # Required for paths with whitespace ADD ["",... ""] .EE .PP دستورالعمل \fBADD\fP فایل‌ها، دایرکتوری‌ها یا نشانی‌های URL فایل‌های راه دور جدید را در سیستم‌فایل کانتینر در مسیر \fB\fR کپی می‌کند. می‌توان چندین منبع \fB\fR را مشخص کرد، اما اگر فایل یا دایرکتوری باشند باید نسبت به دایرکتوری منبع که در حال ساخت است (زمینه ساخت) نسبی باشند. مقدار \fB\fR یک مسیر مطلق یا مسیری نسبت به \fBWORKDIR\fP است که منبع درون کانتینر مقصد در آن کپی می‌شود. اگر آرگومان \fB\fR یک فایل محلی با فرمت فشرده‌سازی شناخته‌شده (tar, gzip, bzip2 و غیره) باشد، در مسیر مشخص‌شده \fB\fR در سیستم‌فایل کانتینر استخراج می‌شود. توجه داشته باشید که تنها فایل‌های فشرده محلی از حالت فشرده خارج می‌شوند، یعنی ویژگی‌های دانلود URL و استخراج آرشیو را نمی‌توان همزمان با هم استفاده کرد. تمامی دایرکتوری‌های جدید با حالت دسترسی 0755 و با uid و gid برابر \fB0\fP ایجاد می‌شوند. .PP \fBCOPY\fP -- دستورالعمل \fBCOPY\fP دو قالب دارد: .EX COPY [--chown=:] [--chmod=] # Required for paths with whitespace COPY [--chown=:] [--chmod=] ["",... ""] .EE .PP دستورالعمل \fBCOPY\fP فایل‌های جدید را از \fB\fR کپی کرده و به سیستم‌فایل کانتینر در مسیر مقصد اضافه می‌کند. منبع \fB\fR باید مسیر یک فایل یا دایرکتوری نسبی نسبت به دایرکتوری ساخت یا یک آدرس URL راه دور باشد. مقدار \fB\fR یک مسیر مطلق یا نسبی نسبت به \fBWORKDIR\fP است. اگر یک فایل آرشیو را \fBCOPY\fP کنید، دقیقاً همان‌طور که در زمینه ساخت قرار دارد و بدون استخراج درون کانتینر قرار می‌گیرد. تمامی فایل‌ها و دایرکتوری‌های جدید با حالت \fB0755\fP و با uid و gid برابر \fB0\fP ساخته می‌شوند. .PP گزینه \fB--chown=:\fR مالکیت فایل‌ها و دایرکتوری‌های جدید را تغییر می‌دهد. از نام‌ها (در صورت تعریف در فایل‌های \fB/etc/passwd\fR و \fB/etc/groups\fR کانتینر) یا شناسه‌های عددی uid و gid پشتیبانی می‌کند. در صورتی که نام کاربر یا گروه در کانتینر یافت نشود، فرآیند ساخت با خطا مواجه خواهد شد. شناسه‌های عددی بدون نیاز به وجود در کانتینر اعمال می‌شوند. .PP گزینه \fB--chmod=\fR حالت مجوز دسترسی فایل‌ها و پوشه‌های جدید را تغییر می‌دهد. .PP فلگ اختیاری \fB--from=name\fR می‌تواند برای کپی کردن فایل‌ها از یک مرحله ساخت نام‌گذاری‌شده پیشین استفاده شود. این فلگ زمینه \fB\fR را از زمینه ساخت به مرحله ساخت نام‌برده تغییر می‌دهد. .PP .PP \fBENTRYPOINT\fP -- دستورالعمل \fBENTRYPOINT\fP دارای دو قالب است: .EX # executable form ENTRYPOINT ["executable", "param1", "param2"]` # run command in a shell - /bin/sh -c ENTRYPOINT command param1 param2 .EE .PP -- دستورالعمل \fBENTRYPOINT\fP به شما در پیکربندی کانتینری که مانند یک فایل اجرایی اجرا می‌شود کمک می‌کند. هنگامی که یک \fBENTRYPOINT\fP تعیین می‌کنید، کل کانتینر طوری رفتار می‌کند که گویی تنها همان فایل اجرایی است. دستورالعمل \fBENTRYPOINT\fP یک دستور ورودی اضافه می‌کند که با ارسال آرگومان‌ها به \fBpodman run\fR بازنویسی نمی‌شود. این تفاوت عمده آن با رفتار \fBCMD\fP است. این قابلیت اجازه می‌دهد تا آرگومان‌ها به entrypoint ارسال شوند؛ برای نمونه دستور \fBpodman run -d\fR آرگومان -d را به \fBENTRYPOINT\fP ارسال می‌کند. پارامترها را یا در آرایه JSON دستور \fBENTRYPOINT\fP مشخص کنید (مانند فرم اجرایی توصیه‌شده در بالا)، یا از یک دستور \fBCMD\fP استفاده کنید. پارامترهای موجود در \fBENTRYPOINT\fP با آرگومان‌های \fBpodman run\fR بازنویسی نمی‌شوند، در حالی که پارامترهای مشخص‌شده از طریق \fBCMD\fP با آرگومان‌های \fBpodman run\fR بازنویسی خواهند شد. اگر برای \fBENTRYPOINT\fP یک رشته ساده مشخص کنید، مانند دستورالعمل \fBCMD\fP در \fB/bin/sh -c\fR اجرا می‌شود: .EX FROM ubuntu ENTRYPOINT wc -l - .EE .PP این به این معنی است که تصویر Containerfile همیشه stdin را به عنوان ورودی دریافت می‌کند (معنی "-")، و تعداد خطوط را چاپ می‌نماید (معنی "-l"). برای تبدیل این رفتار به حالتی اختیاری اما پیش‌فرض، از یک \fBCMD\fP استفاده کنید: .EX FROM ubuntu CMD ["-l", "-"] ENTRYPOINT ["/usr/bin/wc"] .EE .PP \fBVOLUME\fP -- \fBVOLUME ["/data"]\fR دستورالعمل \fBVOLUME\fP یک نقطه اتصال (mount point) با نام مشخص ایجاد می‌کند و آن را به عنوان نگه‌دارنده حجم‌های متصل‌شده خارجی از میزبان اصلی یا سایر کانتینرها علامت‌گذاری می‌نماید. .PP \fBUSER\fP -- \fBUSER daemon\fR نام کاربر یا شناسه UID مورد استفاده برای اجرای دستورات بعدی را تعیین می‌کند. .PP دستورالعمل \fBUSER\fP می‌تواند به صورت اختیاری برای تعیین گروه یا GID نیز به کار رود. تمامی مثال‌های زیر معتبر هستند: USER [user | user:group | uid | uid:gid | user:gid | uid:group ] .PP تا زمانی که دستورالعمل \fBUSER\fP تنظیم نشده باشد، دستورات با دسترسی root اجرا می‌شوند. دستورالعمل USER می‌تواند به هر تعداد بار در Containerfile استفاده شود و تنها بر دستورات بعدی تأثیر می‌گذارد. .PP \fBWORKDIR\fP -- \fBWORKDIR /path/to/workdir\fR دستورالعمل \fBWORKDIR\fP دایرکتوری کاری را برای دستورات \fBRUN\fP، \fBCMD\fP، \fBENTRYPOINT\fP، \fBCOPY\fP و \fBADD\fP پس از خود در Containerfile تنظیم می‌کند. این دستور می‌تواند چندین بار در یک فایل Containerfile تکرار شود. مسیرهای نسبی، نسبت به مسیر دستور قبلی \fBWORKDIR\fP تعریف می‌شوند. برای نمونه: .EX WORKDIR /a WORKDIR b WORKDIR c RUN pwd .EE .PP در مثال بالا، خروجی دستور \fBpwd\fP برابر با \fBa/b/c\fP خواهد بود. .PP \fBARG\fP -- \fBARG [=]\fR .PP دستورالعمل \fBARG\fR متغیری را تعریف می‌کند که کاربران می‌توانند در زمان ساخت با دستورات \fBpodman build\fR و \fBbuildah build\fR و با استفاده از فلگ \fB--build-arg =\fR به سازنده ارسال کنند. اگر کاربر آرگومان ساختی را مشخص کند که در Containerfile تعریف نشده است، فرآیند ساخت یک هشدار نمایش می‌دهد. .PP توجه داشته باشید که دومین دستور FROM در یک Containerfile مقادیر مرتبط با متغیر Arg را به nil تنظیم می‌کند و اگر قرار است بعداً در Containerfile استفاده شوند، باید مجدداً تنظیم شوند. .EX [Warning] One or more build-args [foo] were not consumed .EE .PP نویسنده Containerfile می‌تواند با تعیین یک‌باره \fBARG\fR یک متغیر، یا با تعیین چندین‌باره آن چندین متغیر را تعریف کند. برای نمونه، یک Containerfile معتبر: .EX FROM busybox ARG user1 ARG buildno ... .EE .PP نویسنده Containerfile می‌تواند به صورت اختیاری مقدار پیش‌فرضی را برای دستورالعمل \fBARG\fR مشخص کند: .EX FROM busybox ARG user1=someuser ARG buildno=1 ... .EE .PP اگر یک متغیر \fBARG\fR دارای مقدار پیش‌فرض باشد و هیچ مقداری در زمان ساخت ارسال نشود، سازنده از همان مقدار پیش‌فرض استفاده می‌کند. .PP تعریف متغیر \fBARG\fR از همان خطی که در آن در \fBContainerfile\fR تعریف شده است اعمال می‌شود، نه از زمان استفاده آرگومان در خط فرمان یا جای دیگر. برای نمونه، این Containerfile را در نظر بگیرید: .EX 1 FROM busybox 2 USER ${user:-some_user} 3 ARG user 4 USER $user ... .EE .PP کاربر این فایل را با این دستور می‌سازد: .EX $ podman build --build-arg user=what_user Containerfile .EE .PP مقدار \fBUSER\fR در خط ۲ برابر با \fBsome_user\fR ارزیابی می‌شود زیرا متغیر \fBuser\fR در خط ۳ بعدی تعریف شده است. مقدار \fBUSER\fR در خط ۴ برابر با \fBwhat_user\fR خواهد بود زیرا \fBuser\fR تعریف شده و مقدار \fBwhat_user\fR از خط فرمان ارسال شده است. پیش از تعریف توسط دستورالعمل \fBARG\fR، هرگونه استفاده از یک متغیر منجر به یک رشته خالی می‌شود. .PP .RS .PP \fBهشدار:\fP استفاده از متغیرهای زمان ساخت برای ارسال اطلاعات محرمانه مانند کلیدهای گیت‌هاب، اطلاعات ورود کاربران و غیره توصیه نمی‌شود. مقادیر متغیرهای زمان ساخت برای هر کاربری که از تصویر با دستور \fBpodman history\fR استفاده کند قابل مشاهده است. .RE .PP می‌توانید از دستورالعمل \fBARG\fR یا \fBENV\fR برای تعیین متغیرهایی که در دسترس دستورالعمل \fBRUN\fR قرار دارند استفاده کنید. متغیرهای محیطی تعریف‌شده با دستورالعمل \fBENV\fR همیشه بر دستورالعمل \fBARG\fR هم‌نام خود اولویت دارند. این Containerfile را با دستورالعمل‌های \fBENV\fR و \fBARG\fR در نظر بگیرید: .EX 1 FROM ubuntu 2 ARG CONT_IMG_VER 3 ENV CONT_IMG_VER=v1.0.0 4 RUN echo $CONT_IMG_VER .EE .PP سپس فرض کنید این تصویر با این دستور ساخته می‌شود: .EX $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile .EE .PP در این حالت، دستورالعمل \fBRUN\fR به جای تنظیم \fBARG\fR ارسال‌شده توسط کاربر (\fBv2.0.1\fR)، از مقدار \fBv1.0.0\fR استفاده می‌کند. این رفتار شبیه به یک اسکریپت شل است که در آن متغیری با حوزه محلی، متغیرهای ارسال‌شده به عنوان آرگومان یا به ارث رسیده از محیط را از نقطه تعریف خود بازنویسی می‌کند. .PP با استفاده از مثال بالا اما با تعیین متفاوت \fBENV\fR، می‌توانید تعاملات مفیدتری بین دستورالعمل‌های \fBARG\fR و \fBENV\fR ایجاد کنید: .EX 1 FROM ubuntu 2 ARG CONT_IMG_VER 3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0} 4 RUN echo $CONT_IMG_VER .EE .PP برخلاف دستورالعمل \fBARG\fR، مقادیر \fBENV\fR همیشه در تصویر ساخته‌شده پایدار باقی می‌مانند. اجرای \fBpodman build\fR بدون فلگ --build-arg را در نظر بگیرید: .EX $ podman build Containerfile .EE .PP با استفاده از این مثال Containerfile، مقدار \fBCONT_IMG_VER\fR همچنان در تصویر ماندگار است اما مقدار آن برابر با \fBv1.0.0\fR خواهد بود، زیرا این مقدار پیش‌فرض تنظیم‌شده در خط ۳ توسط دستورالعمل \fBENV\fR است. .PP تکنیک بسط متغیر در این مثال به شما اجازه می‌دهد آرگومان‌ها را از خط فرمان ارسال کرده و با بهره‌گیری از دستورالعمل \fBENV\fR آن‌ها را در تصویر نهایی ماندگار سازید. بسط متغیر تنها برای مجموعه محدودی از دستورالعمل‌های Containerfile پشتیبانی می‌شود. \[la]#environment\-replacement\[ra] .PP موتورهای کانتینر دارای مجموعه‌ای از متغیرهای \fBARG\fR از پیش تعریف‌شده هستند که می‌توانید بدون نیاز به دستورالعمل متناظر \fBARG\fR در Containerfile از آن‌ها استفاده کنید: .IP \(bu 2 \fBHTTP_PROXY\fR .IP \(bu 2 \fBhttp_proxy\fR .IP \(bu 2 \fBHTTPS_PROXY\fR .IP \(bu 2 \fBhttps_proxy\fR .IP \(bu 2 \fBFTP_PROXY\fR .IP \(bu 2 \fBftp_proxy\fR .IP \(bu 2 \fBNO_PROXY\fR .IP \(bu 2 \fBno_proxy\fR .IP \(bu 2 \fBALL_PROXY\fR .IP \(bu 2 \fBall_proxy\fR .PP برای استفاده از این موارد، آن‌ها را در خط فرمان با استفاده از فلگ \fB--build-arg\fR ارسال کنید، برای نمونه: .EX $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com . .EE .PP \fBARG برای پلتفرم/سیستم‌عامل/معماری (Platform/OS/Arch ARG)\fP -- \fBARG \fR .PP هنگام ساخت لیست‌های مانیفست چندمعماری (multi-arch) یا تصاویر برای یک معماری دیگر، اغلب دسترسی به جزئیات پلتفرم در \fBContainerfile\fR مفید است. برای نمونه، هنگام استفاده از دستور \fBRUN curl ...\fR برای نصب باینری مخصوص سیستم‌عامل/معماری خاص در تصویر، یا اگر مشخص باشد که برخی عملیات \fBRUN\fR در هنگام شبیه‌سازی یک معماری خاص ناسازگار بوده یا عملکرد پایینی دارند. .PP چندین متغیر نام‌گذاری‌شده \fBARG\fR در دسترس هستند. هدف هر یک باید از روی نام آن مشخص باشد. \fIبا این حال\fP، در تمام موارد این مقادیر ARG به طور خودکار مقداردهی \fBنمی‌شوند\fR. شما باید همیشه آن‌ها را درون هر بخش \fBFROM\fR در \fBContainerfile\fR اعلان کنید. .PP متغیرهای در دسترس \fBARG \fR با دو پیشوند عرضه می‌شوند: .IP \(bu 2 نام متغیرهای \fBTARGET...\fR جزئیات مربوط به زمینه ساخت در حال اجرا (یعنی «درون» کانتینر) را نشان می‌دهند. این موارد اغلب مفیدترین هستند: .RS .IP \(bu 2 \fBTARGETOS\fR: برای نمونه \fBlinux\fR .IP \(bu 2 \fBTARGETARCH\fR: برای نمونه \fBamd64\fR .IP \(bu 2 \fBTARGETPLATFORM\fR: برای نمونه \fBlinux/amd64\fR .IP \(bu 2 \fBTARGETVARIANT\fR: کاربرد نادر، ویژه برای \fBTARGETARCH\fR .RE .IP \(bu 2 نام متغیرهای \fBBUILD...\fR نشان‌دهنده جزئیات درباره \fIمیزبان\fP انجام‌دهنده ساخت (یعنی «بیرون» کانتینر) هستند: .RS .IP \(bu 2 \fBBUILDOS\fR: سیستم‌عامل میزبان انجام‌دهنده ساخت .IP \(bu 2 \fBBUILDARCH\fR: معماری میزبان انجام‌دهنده ساخت .IP \(bu 2 \fBBUILDPLATFORM\fR: ترکیب سیستم‌عامل/معماری میزبان ساخت .IP \(bu 2 \fBBUILDVARIANT\fR: کاربرد نادر، ویژه برای \fBBUILDARCH\fR .RE .PP یک نمونه \fBContainerfile\fR که از \fBTARGETARCH\fR برای واکشی یک فایل باینری وابسته به معماری استفاده می‌کند می‌تواند چنین باشد: .EX FROM busybox ARG TARGETARCH RUN curl -sSf -O https://example.com/downloads/bin-${TARGETARCH}.zip .EE .PP با فرض اینکه پلتفرم میزبان \fBlinux/amd64\fR بوده و شبیه‌سازی معماری خارجی فعال باشد (مانند \fBqemu-user-static\fR)، اجرای دستور زیر: .EX $ podman build --platform linux/s390x . .EE .PP منجر به اجرای \fBcurl\fR بر روی نشانی \fBhttps://example.com/downloads/bin-s390x.zip\fR و تولید یک تصویر کانتینر متناسب با پلتفرم \fBlinux/s390x\fR خواهد شد. \fBتوجه:\fP شبیه‌سازی اکیداً الزامی نیست؛ این build-argهای ویژه در زمان ساخت با \fBpodman farm build\fR نیز کار می‌کنند. .PP \fBONBUILD\fP -- \fBONBUILD [INSTRUCTION]\fR دستورالعمل \fBONBUILD\fP یک دستورالعمل محرک (تریگر) را به تصویر اضافه می‌کند. این محرک در زمان بعد، یعنی هنگامی که از این تصویر به عنوان پایه برای ساخت تصویر دیگری استفاده می‌شود، اجرا می‌گردد. موتورهای کانتینر محرک را در زمینه ساخت پایین‌دستی اجرا می‌کنند، گویی که این محرک بلافاصله پس از دستورالعمل \fBFROM\fP در Containerfile پایین‌دستی قرار داشته است. .PP شما می‌توانید هر دستورالعمل ساختی را به عنوان یک محرک ثبت کنید. اگر در حال تعریف تصویری برای استفاده به عنوان پایه ساخت سایر تصاویر هستید، محرک بسیار مفید است. برای نمونه، اگر در حال تعریف محیط ساخت یک برنامه کاربردی یا دیمنی هستید که با پیکربندی ویژه کاربر سفارشی می‌شود. .PP تصویری را در نظر بگیرید که به عنوان یک سازنده برنامه پایتون با قابلیت استفاده مجدد در نظر گرفته شده است. این تصویر باید کد منبع برنامه را به یک دایرکتوری خاص اضافه کند و ممکن است لازم باشد پس از آن یک اسکریپت ساخت فراخوانی شود. شما نمی‌توانید در این مرحله صرفاً \fBADD\fP و \fBRUN\fP را فراخوانی کنید، زیرا هنوز به کد منبع برنامه دسترسی ندارید و این کد برای ساخت هر برنامه متفاوت است. .PP -- در اختیار قرار دادن یک فایل Containerfile اولیه به توسعه‌دهندگان برنامه برای کپی-پیست در برنامه‌شان ناکارآمد، مستعد خطا و به‌روزرسانی آن دشوار است زیرا با کدهای ویژه برنامه ترکیب می‌شود. راه‌حل این است که از \fBONBUILD\fP برای ثبت دستورالعمل‌ها از قبل استفاده کنید تا بعداً، در طول مرحله ساخت بعدی اجرا شوند. .SH "همچنین ببینید (SEE ALSO)" .BR buildah (1), .BR podman (1), .BR docker (1) .SH "تاریخچه (HISTORY)" .EX مه ۲۰۱۴، گردآوری‌شده توسط Zac Dover (zdover at redhat dot com) بر اساس مستندات Dockerfile در docker.com فوریه ۲۰۱۵، به‌روزرسانی‌شده توسط Brian Goff (cpuguy83@gmail.com) برای خوانایی بهتر سپتامبر ۲۰۱۵، به‌روزرسانی‌شده توسط Sally O'Malley (somalley@redhat.com) اکتبر ۲۰۱۶، به‌روزرسانی‌شده توسط Addam Hardy (addam.hardy@gmail.com) اوت ۲۰۲۱، تبدیل صفحه راهنمای Dockerfile به Containerfile توسط Dan Walsh (dwalsh@redhat.com) .EE