official images
1.0.0
صور Docker الرسمية هي صور منسقة مستضافة على Docker Hub. المبادئ الرئيسية هي:
التركيز على البرمجيات الحرة ومفتوحة المصدر
دعم أبنية متعددة
تجسيد أفضل ممارسات Dockerfile
إعادة البناء بنشاط للحصول على التحديثات والإصلاحات الأمنية
الالتزام بالتوصيات الأولية
أضف الحد الأدنى من سلوك جودة الحياة لبيئة الحاوية حيثما كان ذلك مناسبًا
راجع وثائق Docker للحصول على نظرة عامة جيدة عالية المستوى حول البرنامج.
في جوهر الأمر، نحن نسعى جاهدين للاستجابة لتوصيات المنبع بشأن الطريقة التي يعتزمون بها استهلاك برامجهم. يتم الاحتفاظ بالعديد من الصور بالتعاون مع المشروع الأولي ذي الصلة إذا لم يتم صيانتها مباشرة من قبلهم. بالإضافة إلى ذلك، نهدف إلى تجسيد أفضل الممارسات لملفات Dockerfiles لتكون بمثابة مرجع عند إنشاء صورك الخاصة أو استخلاصها منها.
(إذا كنت ممثلاً لمنبع توجد له صورة وترغب في المشاركة، فيرجى الاطلاع على قسم الصيانة أدناه!)
تم نقل بعض الصور إلى بنيات أخرى، والعديد منها مدعوم رسميًا (بدرجات متفاوتة).
arm32v6 ): https://hub.docker.com/u/arm32v6/arm32v7 ): https://hub.docker.com/u/arm32v7/arm64v8 ): https://hub.docker.com/u/arm64v8/amd64 ): https://hub.docker.com/u/amd64/windows-amd64 ): https://hub.docker.com/u/winamd64/arm32v5 ): https://hub.docker.com/u/arm32v5/ppc64le ): https://hub.docker.com/u/ppc64le/s390x ): https://hub.docker.com/u/s390x/mips64le ): https://hub.docker.com/u/mips64le/riscv64 ): https://hub.docker.com/u/riscv64/i386 ): https://hub.docker.com/u/i386/ اعتبارًا من 12/09/2017، يتم تضمين هذه البنيات الأخرى ضمن الصور غير البادئة عبر "قوائم البيان" (المعروفة أيضًا باسم "الفهارس" في مواصفات صورة OCI)، بحيث، على سبيل المثال، يجب أن يقوم docker run hello-world تشغيل كما هو على جميع الأنظمة الأساسية المدعومة.
إذا كنت مهتمًا بكيفية بناء هذه السقالات، فتوجه إلى https://doi-janky.infosiftr.net/job/multiarch/ لرؤية بناء السقالات.
راجع قسم الأقواس المتعددة أدناه للحصول على توصيات بشأن إضافة المزيد من البنيات إلى الصورة الرسمية.
نعم! لدينا مستودع مخصص للأسئلة الشائعة حيث نحاول جمع الأسئلة الشائعة الأخرى (سواء المتعلقة بالبرنامج أو بممارساتنا).
شكرًا لك على اهتمامك بمشروع الصور الرسمية لـ Docker! نحن نسعى جاهدين لجعل هذه التعليمات بسيطة ومباشرة قدر الإمكان، ولكن إذا وجدت نفسك ضائعًا، فلا تتردد في البحث عنا على Libera.Chat IRC في القناة #docker-library أو عن طريق إنشاء مشكلة GitHub هنا.
تأكد من التعرف على المستودعات الرسمية على Docker Hub وأفضل الممارسات لكتابة ملفات Dockerfiles في وثائق Docker. ستكون هذه هي أساس عملية المراجعة التي يقوم بها المشرفون الرسميون على الصور. إذا كنت ترغب في أن تتم عملية المراجعة بسلاسة أكبر، فيرجى التأكد من التزام ملف Dockerfile الخاص بك بجميع النقاط المذكورة هناك، وكذلك أدناه، قبل إرسال طلب السحب.
بالإضافة إلى ذلك، يتم حاليًا تخزين أوصاف Hub لهذه الصور بشكل منفصل في مستودع docker-library/docs ، الذي يشرح ملف README.md الخاص به المزيد حول كيفية تنظيمه وكيفية المساهمة فيه. يرجى الاستعداد لإرسال العلاقات العامة هناك أيضًا، في انتظار قبول صورتك هنا.
نظرًا لأن الصور الرسمية تهدف إلى أن تكون أدوات تعليمية لأولئك الجدد في Docker بالإضافة إلى الصور الأساسية للمستخدمين المتقدمين لإنشاء إصدارات الإنتاج الخاصة بهم، فإننا نراجع كل Dockerfile مقترح للتأكد من أنه يلبي الحد الأدنى من معايير الجودة وقابلية الصيانة. في حين أنه من الصعب تحديد بعض هذه المعايير (بسبب الذاتية)، فقد تم تعريف أكبر قدر ممكن هنا، مع الالتزام أيضًا بـ "أفضل الممارسات" حيثما كان ذلك مناسبًا.
يمكن العثور على قائمة مرجعية يمكن للمشرفين استخدامها أثناء المراجعة في NEW-IMAGE-CHECKLIST.md .
يجب معالجة مشكلات الإصدار والإصلاحات الأمنية في الوقت المناسب.
إذا كنت لا تمثل المنبع وأصبحت المنبع مهتمة بالحفاظ على الصورة، فيجب اتخاذ خطوات لضمان الانتقال السلس لصيانة الصورة إلى المنبع.
بالنسبة للمنبعين المهتمين بتولي صيانة المستودع الحالي، فإن الخطوة الأولى هي المشاركة في المستودع الحالي. إن إبداء التعليقات على المشكلات، واقتراح التغييرات، والتعريف بنفسك داخل "مجتمع الصور" (حتى لو كان هذا "المجتمع" هو المشرف الحالي فقط) كلها أماكن مهمة للبدء في ضمان أن الانتقال ليس مفاجئًا للمساهمين والمستخدمين الحاليين.
عند تولي مستودع موجود، يرجى التأكد من الاحتفاظ بسجل Git الكامل للمستودع الأصلي في المستودع الجديد الذي تتم صيانته من قبل المنبع للتأكد من عدم توقف عملية المراجعة أثناء عملية النقل. يمكن تحقيق ذلك بسهولة أكبر عن طريق تفرع الجديد من المستودع الحالي، ولكن يمكن تحقيقه أيضًا عن طريق جلب الالتزامات مباشرة من الأصل ودفعها إلى الريبو الجديد (على سبيل المثال، git fetch https://github.com/jsmith/example.git master ، git rebase FETCH_HEAD ، git push -f ). على GitHub، البديل هو نقل ملكية مستودع git. يمكن تحقيق ذلك دون منح أي من مسؤولي المجموعة حق الوصول إلى مستودع المالك الآخر:
يجب أن تؤدي إعادة إنشاء Dockerfile نفسه إلى تجميع نفس الإصدار من الصورة، حتى لو حدث الإصدار الثاني بعدة إصدارات لاحقًا، أو يجب أن يفشل البناء تمامًا، بحيث لا تنتهي عملية إعادة البناء غير المقصودة لملف Dockerfile الموسوم بـ 0.1.0 يحتوي على 0.2.3 . على سبيل المثال، إذا كنت تستخدم apt لتثبيت البرنامج الرئيسي للصورة، فتأكد من تثبيته على إصدار محدد (على سبيل المثال: ... apt-get install -y my-package=0.1.0 ... ). بالنسبة للحزم التابعة المثبتة بواسطة apt لا توجد عادة حاجة لتثبيتها على إصدار ما.
لا يمكن استخلاص أي صور رسمية من الصور غير الرسمية أو الاعتماد عليها (مما يسمح scratch غير الصورة والاستثناءات المحدودة عمدًا والمثبتة في .external-pins - راجع أيضًا .external-pins/list.sh ).
يجب أن توفر جميع الصور الرسمية واجهة متسقة. يجب أن يكون المستخدم المبتدئ قادرًا على docker run official-image bash (أو sh ) دون الحاجة إلى التعرف على --entrypoint . من الجيد أيضًا أن يستفيد المستخدمون المتقدمون من نقطة الدخول، حتى docker run official-image --arg1 --arg2 دون الحاجة إلى تحديد الملف الثنائي للتنفيذ.
إذا كانت عملية بدء التشغيل لا تحتاج إلى وسائط، فما عليك سوى استخدام CMD :
CMD [ "irb" ] إذا كانت هناك تهيئة يجب إجراؤها في البداية، مثل إنشاء قاعدة البيانات الأولية، فاستخدم ENTRYPOINT مع CMD :
ENTRYPOINT [ "/docker-entrypoint.sh" ]
CMD [ "postgres" ] تأكد من أن docker run official-image bash (أو sh ) يعمل أيضًا. أسهل طريقة هي التحقق من الأمر المتوقع وإذا كان شيئًا آخر، فما عليك سوى exec "$@" (تشغيل كل ما تم تمريره، مع الحفاظ على هروب الوسائط بشكل صحيح).
#! /bin/sh
set -e
# this if will check if the first argument is a flag
# but only works if all arguments require a hyphenated flag
# -v; -SL; -f arg; etc will work, but not arg1 arg2
if [ " $# " -eq 0 ] || [ " ${1 # -} " != " $1 " ] ; then
set -- mongod " $@ "
fi
# check for the expected command
if [ " $1 " = ' mongod ' ] ; then
# init db stuff....
# use gosu (or su-exec) to drop to a non-root user
exec gosu mongod " $@ "
fi
# else default to run whatever the user wanted like "bash" or "sh"
exec " $@ " إذا كانت الصورة تحتوي فقط على الملف القابل للتنفيذ الرئيسي والمكتبات المرتبطة به (أي بدون Shell)، فمن الجيد استخدام الملف القابل للتنفيذ كـ ENTRYPOINT ، نظرًا لأن هذا هو الشيء الوحيد الذي يمكن تشغيله:
ENTRYPOINT [ "fully-static-binary" ]
CMD [ "--help" ] المؤشر الأكثر شيوعًا لمعرفة ما إذا كان هذا مناسبًا هو أن صورة Dockerfile تبدأ من scratch ( FROM scratch ).
حاول أن تجعل Dockerfile سهل الفهم/القراءة. قد يكون من المغري، من أجل الإيجاز، وضع تفاصيل تهيئة معقدة في برنامج نصي مستقل وإضافة أمر RUN في Dockerfile . ومع ذلك، يؤدي هذا إلى أن يكون ملف Dockerfile الناتج معتمًا بشكل مفرط، ومن غير المرجح أن تنجح ملفات Dockerfile هذه في المراجعة. بدلاً من ذلك، يوصى بوضع جميع أوامر التهيئة في Dockerfile كمجموعات أوامر RUN أو ENV مناسبة. للعثور على أمثلة جيدة، انظر إلى الصور الرسمية الحالية.
بعض الأمثلة في وقت الكتابة:
باتباع إرشادات Docker، يوصى بشدة أن تكون الصورة الناتجة مجرد مشكلة واحدة لكل حاوية؛ ويعني هذا في الغالب عملية واحدة فقط لكل حاوية، لذلك ليست هناك حاجة لنظام init كامل. هناك حالتان حيث تكون عملية تشبه init مفيدة للحاوية. الأول هو التعامل مع الإشارات. إذا كانت العملية التي تم إطلاقها لا تتعامل مع SIGTERM عن طريق الخروج، فلن يتم قتلها لأنها PID 1 في الحاوية (راجع "ملاحظة" في نهاية قسم المقدمة في مستندات عامل الإرساء). الوضع الثاني سيكون جني الزومبي. إذا ولدت العملية عمليات فرعية ولم تحصدها بشكل صحيح، فسوف تؤدي إلى جدول عمليات كامل، مما قد يمنع النظام بأكمله من إنتاج أي عمليات جديدة. لكل من هذه المخاوف نوصي تيني. إنه صغير بشكل لا يصدق، ولديه الحد الأدنى من التبعيات الخارجية، ويملأ كل من هذه الأدوار، ويقوم فقط بالأجزاء الضرورية من الحصاد وإعادة توجيه الإشارة.
تأكد من استخدام tini في CMD أو ENTRYPOINT حسب الاقتضاء.
من الأفضل تثبيت تيني من حزمة التوزيع المتوفرة (مثل apt-get install tini ). إذا لم يكن تيني متاحًا في توزيعتك أو كان قديمًا جدًا، فإليك مقتطف من ملف Dockerfile لإضافته في تيني:
# Install tini for signal processing and zombie killing
ENV TINI_VERSION v0.18.0
ENV TINI_SIGN_KEY 595E85A6B1B4779EA4DAAEC70B588DFF0527A9B7
RUN set -eux;
wget -O /usr/local/bin/tini "https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini" ;
wget -O /usr/local/bin/tini.asc "https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini.asc" ;
export GNUPGHOME= "$(mktemp -d)" ;
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys "$TINI_SIGN_KEY" ;
gpg --batch --verify /usr/local/bin/tini.asc /usr/local/bin/tini;
command -v gpgconf && gpgconf --kill all || :;
rm -r "$GNUPGHOME" /usr/local/bin/tini.asc;
chmod +x /usr/local/bin/tini;
tini --versionهذا هو المكان الذي تنتهي فيه التجربة بالتفوق على التوثيق للطريق إلى التنوير، ولكن النصائح التالية قد تساعد:
تجنب COPY / ADD كلما أمكن ذلك، ولكن عند الضرورة، كن محددًا قدر الإمكان (على سبيل المثال، COPY one-file.sh /somewhere/ بدلاً من COPY . /somewhere ).
والسبب في ذلك هو أن ذاكرة التخزين المؤقت لتعليمات COPY تعتبر تغييرات mtime الملف بمثابة عطل في ذاكرة التخزين المؤقت، مما قد يجعل سلوك ذاكرة التخزين المؤقت لـ COPY غير متوقع في بعض الأحيان، خاصة عندما يكون .git جزءًا مما يجب COPY (على سبيل المثال).
تأكد من أن الأسطر التي من غير المرجح أن تتغير تأتي قبل الأسطر التي من المرجح أن تتغير (مع التحذير بأن كل سطر يجب أن يولد صورة لا تزال تعمل بنجاح دون افتراضات الأسطر اللاحقة).
على سبيل المثال، السطر الذي يحتوي على رقم إصدار البرنامج ( ENV MYSOFTWARE_VERSION 4.2 ) يجب أن يأتي بعد السطر الذي يقوم بإعداد ملف .list لمستودع APT ( RUN echo 'deb http://example.com/mysoftware/debian some-suite main' > /etc/apt/sources.list.d/mysoftware.list ).
يجب كتابة Dockerfile للمساعدة في تخفيف هجمات الاعتراض أثناء الإنشاء. تركز متطلباتنا على ثلاثة أهداف رئيسية: التحقق من المصدر، والتحقق من المؤلف، والتحقق من المحتوى؛ ويتم تحقيق ذلك على التوالي من خلال ما يلي: استخدام https حيثما أمكن ذلك؛ واستيراد مفاتيح PGP ببصمة الإصبع الكاملة في Dockerfile للتحقق من التوقيعات؛ تضمين المجاميع الاختبارية مباشرةً في Dockerfile . وينبغي استخدام الثلاثة عندما يكون ذلك ممكنا. يمكن استخدام https والمجموع الاختباري المضمن فقط في حالة عدم نشر أي توقيع. كملاذ أخير، يكون المجموع الاختباري المضمن مقبولاً إذا لم يكن الموقع مزودًا بـ https ولا يوجد توقيع.
الغرض من التوصية باستخدام https لتنزيل العناصر المطلوبة هو التأكد من أن التنزيل يتم من مصدر موثوق به مما يجعل الاعتراض أكثر صعوبة.
الغرض من التوصية بالتحقق من توقيع PGP هو التأكد من أن المستخدم المصرح له فقط هو الذي قام بنشر القطعة الأثرية المحددة. عند استيراد مفاتيح PGP، برجاء استخدام خدمة keys.openpgp.org عندما يكون ذلك ممكنًا (يُفضل خلاف ذلك keyserver.ubuntu.com ). راجع أيضًا قسم الأسئلة الشائعة حول المفاتيح والتحقق.
الغرض من التوصية بالتحقق من المجموع الاختباري هو التحقق من أن القطعة الأثرية كما هو متوقع. وهذا يضمن أنه عند تغيير المحتوى البعيد، سيتغير ملف Dockerfile أيضًا وسيوفر ذاكرة تخزين مؤقت طبيعية docker build . كمكافأة، يمنع هذا أيضًا تنزيل عناصر أحدث من المتوقع عن طريق الخطأ على ملفات ذات إصدار سيئ.
فيما يلي بعض الأمثلة:
المفضل : التنزيل عبر https، واستيراد بصمة الإصبع الكاملة لمفتاح PGP والتحقق من asc ، والتحقق من المجموع الاختباري المضمن.
ENV PYTHON_DOWNLOAD_SHA512 (sha512-value-here)
RUN set -eux;
curl -fL "https://www.python.org/ftp/python/$PYTHON_VERSION/Python-$PYTHON_VERSION.tar.xz" -o python.tar.xz;
curl -fL "https://www.python.org/ftp/python/$PYTHON_VERSION/Python-$PYTHON_VERSION.tar.xz.asc" -o python.tar.xz.asc;
export GNUPGHOME= "$(mktemp -d)" ;
# gpg: key F73C700D: public key "Larry Hastings <[email protected]>" imported
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 97FC712E4C024BBEA48A61ED3A5CA953F73C700D;
gpg --batch --verify python.tar.xz.asc python.tar.xz;
rm -r "$GNUPGHOME" python.tar.xz.asc;
echo "$PYTHON_DOWNLOAD_SHA512 *python.tar.xz" | sha512sum --strict --check;
# installالبديل : تم استيراد بصمة المفتاح الكامل إلى apt والتي ستتحقق من التوقيعات والمجاميع الاختبارية عند تنزيل الحزم وتثبيتها.
RUN set -eux;
key= 'A4A9406876FCBD3C456770C88C718D3B5072E1F5' ;
export GNUPGHOME= "$(mktemp -d)" ;
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys "$key" ;
gpg --batch --armor --export "$key" > /etc/apt/trusted.gpg.d/mysql.gpg.asc;
gpgconf --kill all;
rm -rf "$GNUPGHOME" ;
apt-key list > /dev/null
RUN set -eux;
echo "deb http://repo.mysql.com/apt/debian/ bookworm mysql-${MYSQL_MAJOR}" > /etc/apt/sources.list.d/mysql.list;
apt-get update;
apt-get install -y mysql-community-client= "${MYSQL_VERSION}" mysql-community-server-core= "${MYSQL_VERSION}" ;
rm -rf /var/lib/apt/lists/*;
# ... (كملاحظة جانبية، rm -rf /var/lib/apt/lists/* هو تقريبًا عكس apt-get update - فهو يضمن أن الطبقة لا تتضمن ~ 8 ميجابايت إضافية من بيانات قائمة حزم APT، و يفرض الاستخدام المناسب apt-get update .)
بديل أقل أمانًا : قم بتضمين المجموع الاختباري في Dockerfile .
ENV RUBY_DOWNLOAD_SHA256 (sha256-value-here)
RUN set -eux;
curl -fL -o ruby.tar.gz "https://cache.ruby-lang.org/pub/ruby/$RUBY_MAJOR/ruby-$RUBY_VERSION.tar.gz" ;
echo "$RUBY_DOWNLOAD_SHA256 *ruby.tar.gz" | sha256sum --strict --check;
# installملاحظة: يجب اعتبار استخدام SHA1 أو MD5 "المجموع الاختباري للملاذ الأخير" حيث يعتبر كلاهما غير آمن بشكل عام:
غير مقبول : قم بتنزيل الملف عبر http(s) بدون التحقق.
RUN curl -fL "https://julialang.s3.amazonaws.com/bin/linux/x64/${JULIA_VERSION%[.-]*}/julia-${JULIA_VERSION}-linux-x86_64.tar.gz" | tar ...
# install افتراضيًا، يتم تنفيذ حاويات Docker بامتيازات منخفضة: إمكانات Linux المدرجة في القائمة البيضاء، ومجموعات التحكم، وملف تعريف Seccomp الافتراضي (1.10+ مع دعم المضيف). قد تتطلب البرامج التي يتم تشغيلها في حاوية امتيازات إضافية حتى تعمل بشكل صحيح، ويوجد عدد من خيارات سطر الأوامر لتخصيص تنفيذ الحاوية. راجع docker run Reference وSeccomp for Docker كمرجع.
يجب أن تحدد المستودعات الرسمية التي تتطلب امتيازات إضافية الحد الأدنى من خيارات سطر الأوامر حتى يعمل البرنامج، وقد يتم رفضها إذا أدى ذلك إلى مشكلات كبيرة تتعلق بإمكانية النقل أو الأمان. بشكل عام، --privileged غير مسموح به، ولكن قد يكون الجمع بين خيارات --cap-add و --device مقبولاً. بالإضافة إلى ذلك، يمكن أن يكون --volume أمرًا صعبًا نظرًا لوجود العديد من مواقع نظام الملفات المضيف التي تسبب مشكلات في قابلية النقل/الأمان (على سبيل المثال مقبس X11).
بالنسبة لتحديثات الصور التي تشكل إصلاحًا أمنيًا، هناك بعض الأشياء التي نوصي بها للمساعدة في ضمان دمج التحديث الخاص بك وإنشائه وإصداره في أسرع وقت ممكن:
[email protected] قبل بضعة أيام (عمل) لتزويدنا بتنبيه وتقدير للتوقيت (حتى نتمكن من جدولة الوقت للتحديث الوارد بشكل مناسب).[security] في عنوان طلب السحب الخاص بك (على سبيل المثال، [security] Update FooBar to 1.2.5, 1.3.7, 2.0.1 ). يمكن لكل ريبو تحديد بنيات متعددة لأي وجميع العلامات. إذا لم يتم تحديد بنية، فسيتم إنشاء الصور في Linux على amd64 (المعروف أيضًا باسم x86-64). لتحديد بنيات أكثر أو مختلفة، استخدم حقل Architectures (قائمة مفصولة بفواصل، يتم قطع المسافات البيضاء). تم العثور على بنيات صالحة في ملف oci-platform.go الخاص بـ Bashbrew:
amd64arm32v6arm32v7arm64v8i386mips64leppc64leriscv64s390xwindows-amd64 يجب أن تكون Architectures أي علامة معينة مجموعة فرعية صارمة من Architectures العلامة التي FROM .
يجب أن تحتوي الصور على Dockerfile واحد لكل إدخال في ملف المكتبة والذي يمكن استخدامه لبنيات متعددة. وهذا يعني أن كل بنية مدعومة سيكون لها نفس السطر FROM (على سبيل المثال FROM debian:bookworm ). راجع golang و docker و haproxy و php للحصول على أمثلة لملفات المكتبة التي تستخدم Dockerfile واحدًا لكل إدخال وراجع مستودعات git الخاصة بها على سبيل المثال Dockerfile s.
إذا كانت أجزاء مختلفة من ملف Dockerfile تحدث فقط في بنية واحدة أو أخرى، فاستخدم تدفق التحكم (على سبيل المثال if / case ) مع dpkg --print-architecture أو apk -print-arch لاكتشاف بنية مساحة المستخدم. استخدم uname فقط لاكتشاف البنية عندما لا يمكن تثبيت أدوات أكثر دقة. راجع golang للحصول على مثال حيث تتطلب بعض البنيات إنشاء ثنائيات من حزم المصدر الأولية وبعضها يقوم فقط بتنزيل الإصدار الثنائي.
بالنسبة للصور الأساسية مثل debian سيكون من الضروري أن يكون لديك Dockerfile مختلف وسياق البناء من أجل ADD ثنائيات محددة للهندسة المعمارية وهذا استثناء صالح لما سبق. وبما أن هذه الصور تستخدم نفس Tags ، فيجب أن تكون في نفس الإدخال. استخدم الحقول الخاصة بالبنية الخاصة بـ GitRepo و GitFetch و GitCommit و Directory ، وهي البنية المتسلسلة بالواصلة ( - ) والحقل (على سبيل المثال، arm32v7-GitCommit ). أي بنية لا تحتوي على حقل خاص بالبنية ستستخدم الحقل الافتراضي (على سبيل المثال، لا يوجد arm32v7-Directory يعني أنه سيتم استخدام Directory لـ arm32v7 ). راجع ملفات debian أو ubuntu الموجودة في المكتبة للحصول على أمثلة. فيما يلي مثال لـ hello-world :
Maintainers: Tianon Gravi <[email protected]> (@tianon),
Joseph Ferguson <[email protected]> (@yosifkit)
GitRepo: https://github.com/docker-library/hello-world.git
GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
Tags: latest
Architectures: amd64, arm32v5, arm32v7, arm64v8, ppc64le, s390x
# all the same commit; easy for us to generate this way since they could be different
amd64-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
amd64-Directory: amd64/hello-world
arm32v5-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
arm32v5-Directory: arm32v5/hello-world
arm32v7-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
arm32v7-Directory: arm32v7/hello-world
arm64v8-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
arm64v8-Directory: arm64v8/hello-world
ppc64le-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
ppc64le-Directory: ppc64le/hello-world
s390x-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
s390x-Directory: s390x/hello-world
Tags: nanoserver
Architectures: windows-amd64
# if there is only one architecture, you can use the unprefixed fields
Directory: amd64/hello-world/nanoserver
# or use the prefixed versions
windows-amd64-GitCommit: 7d0ee592e4ed60e2da9d59331e16ecdcadc1ed87
Constraints: nanoserver
راجع قسم تنسيق التعليمات لمزيد من المعلومات حول تنسيق ملف المكتبة.
لا ينبغي الاستخفاف باقتراح صورة رسمية جديدة. نحن نتوقع ونطلب الالتزام بالحفاظ على صورتك (بما في ذلك التحديثات في الوقت المناسب بشكل خاص حسب الاقتضاء، كما هو مذكور أعلاه).
ملفات تعريف المكتبة هي ملفات نصية عادية موجودة في دليل library/ مستودع official-images . يتحكم كل ملف مكتبة في المجموعة الحالية "المدعومة" من علامات الصور التي تظهر في وصف Docker Hub. العلامات التي تمت إزالتها من ملف المكتبة لا تتم إزالتها من Docker Hub، بحيث يمكن أن تظل الإصدارات القديمة متاحة للاستخدام، ولكن لا يتم صيانتها بواسطة المنبع أو المشرف على الصورة الرسمية. يتم إنشاء العلامات الموجودة في ملف المكتبة فقط من خلال تحديث ملف المكتبة هذا أو كنتيجة لتحديث صورته الأساسية (على سبيل المثال، سيتم إعادة بناء صورة FROM debian:bookworm عند إنشاء debian:bookworm ). سيتم إعادة بناء ما هو موجود في ملف المكتبة فقط عندما تحتوي القاعدة على تحديثات.
في ضوء هذه السياسة، من المفيد توضيح بعض الحالات: الإصدارات المعادة، وإصدار المرشحين، وبناء التكامل المستمر. عندما يتم اقتراح مستودع جديد، فمن الشائع تضمين بعض الإصدارات القديمة غير المدعومة في طلب السحب الأولي مع الموافقة على إزالتها مباشرة بعد القبول. لا تخلط بين هذا وبين الأرشيف التاريخي الشامل فهذا ليس هو المقصود. هناك حالة شائعة أخرى حيث يتم تمديد مصطلح "مدعوم" قليلاً وهي مع المرشحين للإصدار. إن الإصدار المرشح هو في الواقع مجرد اصطلاح تسمية لما يُتوقع أن يكون إصدارات قصيرة العمر، لذا فهي مقبولة تمامًا ومشجعة. على عكس الإصدار المرشح، فإن إصدارات التكامل المستمر التي تحتوي على دورة إصدار مؤتمتة بالكامل استنادًا إلى التزامات التعليمات البرمجية أو جدول زمني منتظم ليست مناسبة.
يوصى بشدة بتصفح بعض محتويات library/ الملفات الحالية (والتاريخ للتعرف على كيفية تغيرها بمرور الوقت) قبل إنشاء محتويات جديدة للتعرف على التقاليد السائدة والمساعدة في تبسيط عملية المراجعة (لذلك أنه يمكننا التركيز على المحتوى بدلاً من التنسيق المقصور على فئة معينة أو استخدام/تسمية العلامة).
سيحدد اسم ملف التعريف اسم مستودع الصور الذي يقوم بإنشائه على Docker Hub. على سبيل المثال، سيقوم ملف library/ubuntu بإنشاء علامات في مستودع ubuntu .
يجب أن تعكس علامات المستودع الإصدارات أو الاختلافات في المنبع. على سبيل المثال، Ubuntu 14.04 يُعرف أيضًا باسم Ubuntu Trusty Tahr، ولكن في كثير من الأحيان ببساطة Ubuntu Trusty (خاصة في الاستخدام)، لذا فإن ubuntu:14.04 (رقم الإصدار) و ubuntu:trusty (اسم الإصدار) هما اسمان مستعاران مناسبان لنفس محتويات الصورة. في Docker، تعد العلامة latest حالة خاصة، ولكنها تسمية خاطئة إلى حد ما؛ latest حقًا هو العلامة "الافتراضية". عندما يقوم أحد الأشخاص docker run xyz ، يفسر Docker ذلك على أنه يعني docker run xyz:latest . بالنظر إلى هذه الخلفية، لا توجد علامة أخرى تحتوي على السلسلة latest ، نظرًا لأنه ليس شيئًا يُتوقع من المستخدمين أو يُشجعون على كتابته فعليًا (على سبيل المثال، يجب استخدام xyz:latest كـ xyz ببساطة). وبعبارة أخرى، يجب أن يكون الاسم المستعار لـ "أعلى إصدار لسلسلة 2.2 من XYZ" هو xyz:2.2 ، وليس xyz:2.2-latest . وبالمثل، إذا كان هناك متغير Alpine لـ xyz:latest ، فيجب أن يكون مستعارًا كـ xyz:alpine ، وليس xyz:alpine-latest أو xyz:latest-alpine .
من المستحسن بشدة أن يتم إعطاء علامات أرقام الإصدار أسماء مستعارة تجعل من السهل على المستخدم البقاء على الإصدار "الأحدث" من سلسلة معينة. على سبيل المثال، في ضوء إصدارات برنامج XYZ المدعومة حاليًا 2.3.7 و2.2.4، ستكون الأسماء المستعارة المقترحة هي Tags: 2.3.7, 2.3, 2, latest Tags: 2.2.4, 2.2 ، على التوالي. في هذا المثال، يمكن للمستخدم استخدام xyz:2.2 لاستخدام أحدث إصدار تصحيح من السلسلة 2.2 بسهولة، أو xyz:2 إذا كانت هناك حاجة إلى دقة أقل (تعد Python مثالًا جيدًا على المكان الذي يكون فيه ذلك مفيدًا بشكل واضح -- python:2 و python:3 مختلفان تمامًا، ويمكن اعتبارهما latest علامة لكل من مسارات الإصدار الرئيسية لـ Python).
كما هو موضح أعلاه، latest هو في الواقع "افتراضي"، وبالتالي فإن الصورة التي تمثل اسمًا مستعارًا لها يجب أن تعكس الإصدار أو الإصدار الذي يجب على مستخدمي البرنامج استخدامه إذا كانوا لا يعرفون أو لا يهتمون بالإصدار الذي يستخدمونه. باستخدام Ubuntu كمثال، يشير ubuntu:latest إلى أحدث إصدار من LTS، نظرًا لأنه ما يجب أن يستخدمه غالبية المستخدمين إذا كانوا يعرفون أنهم يريدون Ubuntu ولكنهم لا يعرفون أو يهتمون بالإصدار (خاصة بالنظر إلى أنه سيكون الإصدار الأفضل) الإصدار الأكثر "ثباتًا" ودعمًا جيدًا في أي وقت).
يعتمد تنسيق ملف البيان رسميًا على RFC 2822، وعلى هذا النحو يجب أن يكون مألوفًا للأشخاص الذين هم على دراية بالفعل بـ "رؤوس" العديد من بروتوكولات/تنسيقات الإنترنت الشائعة مثل HTTP أو البريد الإلكتروني.
الإضافات الأساسية مستوحاة من الطريقة التي يستخدم بها دبيان عادة 2822 - أي، يتم تجاهل الأسطر التي تبدأ بـ # ويتم فصل "الإدخالات" بسطر فارغ.
الإدخال الأول هو البيانات الوصفية "العالمية" للصورة. الحقل الوحيد المطلوب في الإدخال العام هو Maintainers ، ويتم فصل قيمته بفواصل بتنسيق Name <email> (@github) أو Name (@github) . سيكون أي حقل محدد في الإدخال العام هو الحقل الافتراضي لبقية الإدخالات ويمكن تجاوزه في إدخال فردي.
# this is a comment and will be ignored
Maintainers: John Smith <[email protected]> (@example-jsmith),
Anne Smith <[email protected]> (@example-asmith)
GitRepo: https://github.com/example/docker-example.git
GitCommit: deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
# this is also a comment, and will also be ignored
Tags: 1.2.3, 1.2, 1, latest
Directory: 1
Tags: 2.0-rc1, 2.0-rc, 2-rc, rc
GitRepo: https://github.com/example/docker-example-rc.git
GitFetch: refs/heads/2.0-pre-release
GitCommit: beefdeadbeefdeadbeefdeadbeefdeadbeefdead
Directory: 2
File: Dockerfile-to-use
سيقوم Bashbrew بجلب التعليمات البرمجية من مستودع Git ( GitRepo ) عند الالتزام المحدد ( GitCommit ). إذا لم يكن الالتزام المشار إليه متاحًا عن طريق جلب master GitRepo المرتبط، يصبح من الضروري توفير قيمة لـ GitFetch لإخبار Bashbrew بالمرجع الذي يجب جلبه للحصول على الالتزام الضروري.
سيتم وضع علامة على الصورة المبنية كـ <manifest-filename>:<tag> (على سبيل المثال، library/golang بقيمة Tags 1.6, 1, latest ستنشئ علامات golang:1.6 و golang:1 و golang:latest ).
اختياريًا، في حالة وجود Directory ، سيبحث Bashbrew عن Dockerfile داخل الدليل الفرعي المحدد بدلاً من الجذر (وسيتم استخدام Directory باعتباره "سياقًا" للإنشاء بدلاً من المستوى الأعلى للمستودع). إذا كان File موجودًا، فسيتم استخدام اسم الملف المحدد بدلاً من Dockerfile .
راجع قسم متعدد القوس للحصول على تفاصيل حول كيفية تحديد GitRepo أو GitFetch أو GitCommit أو Directory مختلف لبنية محددة.
library/ المجلد. سيكون اسمه هو اسم المستودع الخاص بك على Hub. Bashbrew ( bashbrew ) هي أداة لاستنساخ الصور الرسمية لـ Docker وإنشائها ووضع علامات عليها ودفعها. راجع README الخاص بـ Bashbrew لمزيد من المعلومات.
