ایمیج را ساخته‌ایم؛ پس چرا ماشین هم‌تیمی آن را پیدا نمی‌کند؟“But didn’t we already build the image?”

برنامه را ساختیم، image هم روی لپ‌تاپ خودمان کاملاً سالم است. حالا هم‌تیمی‌ات روی ماشین خودش همان نام را می‌زند و Docker می‌گوید image را پیدا نمی‌کند. سؤال طبیعی این است: «مگر همین چند دقیقه پیش image را نساختیم؟» بله؛ اما فقط روی ماشین خودمان. هنوز جایی منتشرش نکرده‌ایم که ماشین دیگری بتواند آن را بگیرد.

In Chapter 4 we built the tiny demo-web application. Later chapters ran it, configured it, and checked its health. Now another person uses the same name and Docker says it cannot find the image locally.

$ docker run my-app:1.0
Unable to find image 'my-app:1.0' locally
docker: pull access denied for my-app, repository does not exist or may require authorization.

تا اینجا همه‌چیز محلی بود: build انجام می‌شد و image در image store همان Docker Engine می‌نشست. برای اینکه سرور یا هم‌تیمی دقیقاً همان خروجی ساخته‌شده را اجرا کند، باید آن را به جایی بفرستیم که هر دو طرف به آن دسترسی دارند. اینجا registry وارد داستان می‌شود؛ نه به‌عنوان موتور اجرای تازه، بلکه به‌عنوان محل توزیع image.

The first line does not say the app is broken or that no image was ever built. It says this machine has no local image under that name. Docker then tried the default registry, but that reference did not identify an accessible repository. The image exists on your laptop; you have not published it anywhere yet.

این همان فاصله‌ای است که registry پُر می‌کند: یک سرویس برای نگه‌داری و توزیع imageها. قرار نیست با تعریف شروع کنیم؛ اول مسیر حرکت image را ببینیم.

A registry fills that gap: it stores and distributes images. Rather than beginning with a definition, let’s first trace where the image moves.

اول آدرس را درست بخوان: registry کجاست و repository کدام است؟A registry is not the same thing as a repository

قبل از اولین push، چند اسم شبیه هم داریم که اگر قاطی شوند خطاها گیج‌کننده می‌شوند. registry سرویس میزبان imageهاست؛ repository مجموعهٔ نسخه‌های یک image در همان registry است؛ namespace هم معمولاً مالک یا تیم را مشخص می‌کند. tag در انتها فقط برچسبی خوانا برای یکی از نسخه‌هاست.

A registry is the service or host that distributes images. Inside it, repositories group images for an application, and each repository can have multiple tags. Docker Hub is one registry, not “the registry.” GHCR, GitLab Container Registry, cloud registries, and private organizational registries are other examples.

پس در نامی مثل registry.example.net/team/codenames-web:1.0 هر تکه یک سؤال را جواب می‌دهد: «کجا؟»، «برای چه تیمی؟»، «کدام image؟» و «کدام برچسب؟». وقتی push با خطای دسترسی یا نام اشتباه می‌شکند، همین چهار بخش اولین چیزهایی‌اند که باید آرام و جداگانه بررسی کنی.

Build the reference gradually. nginx is a short name; nginx:alpine adds a tag. Your own application needs a namespace: YOUR_ACCOUNT/my-app:1.0. For another registry, include its host too: registry.example.net/team/my-app:1.0.

وقتی registry نوشته نشده، Docker معمولاً Docker Hub را پیش‌فرض می‌گیرد. نام بدون namespace مثل nginx به مسیر رسمی پیش‌فرض Hub می‌رود؛ اما نامی که تو روی لپ‌تاپ با my-app ساخته‌ای به‌خودی‌خود به حساب تو اشاره نمی‌کند. برای push و pull برنامهٔ خودت، namespace درست را صریح بنویس.

When no registry host is written, Docker normally defaults to Docker Hub. A short name such as nginx resolves through Hub’s default official-image namespace. A local image you called my-app does not automatically point to your account. For your own image, write the intended namespace explicitly.

حالا که هر تکه را می‌شناسی، می‌توانی قالب کلی را بخوانی: [HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]. بخش‌های registry میزبان و tag ممکن است حذف شوند و Docker برایشان پیش‌فرض بگذارد؛ namespace هم در نام کوتاه imageهای رسمی Docker Hub معمولاً library است.

Now that you know each part, read the general pattern: [HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]. The registry host and tag may be omitted, in which case Docker applies defaults; short references for Docker Hub official images normally use the library namespace.

Tag تازه، image تازه نمی‌سازدTagging an image does not copy it

فرض کن image محلی‌ات اسم codenames-web:1.0 دارد، اما registry انتظار دارد namespace هم در نام باشد. لازم نیست دوباره build کنی. با docker tag فقط یک نام تازه به همان image می‌دهی؛ لایه‌ها کپی نمی‌شوند و شناسهٔ image عوض نمی‌شود.

Chapter 4 built the image as demo-web:1.0. First inspect what that name refers to. Then add a publication name that points to the same image.

docker image ls demo-web
docker image inspect demo-web:1.0 --format '{{.Id}}'

این تفاوت ساده بعداً خیلی مهم می‌شود: build محتوا می‌سازد، tag به همان محتوا نام دیگری می‌دهد و push آن نام و لایه‌های لازم را به registry می‌فرستد. اگر این سه مرحله را از هم جدا ببینی، بخش بزرگی از خطاهای انتشار قابل‌فهم می‌شود.

The image ls output lists tags present on this machine. The IMAGE ID identifies local image content; it does not prove the image was published. Replace the placeholder with your actual account namespace:

docker tag demo-web:1.0 YOUR_ACCOUNT/codenames-web:1.0
docker image ls --digests YOUR_ACCOUNT/codenames-web

دو سطر در جدول ممکن است IMAGE ID یکسان داشته باشند. این یعنی دو نام محلی به یک image اشاره می‌کنند؛ docker tag همهٔ layerها را کپی نکرده و هنوز هیچ بایتی به اینترنت نرفته است. اسم جدید مثل برچسب روی همان جعبه است، نه جعبهٔ دوم.

The two rows may show the same IMAGE ID. That means two local names refer to the same image. docker tag did not copy all the layers or send anything over the network. It is another label on the same box, not a second box.

Tag برای آدم‌هاست؛ digest برای اشاره به محتوای دقیقA tag is readable; a digest identifies exact registry content

Tagهایی مثل 1.0 یا 1.1.3 خوانا هستند، اما می‌توانند بعداً به محتوای دیگری اشاره کنند. حتی latest هم جادویی نیست؛ فقط یک tag با همین نام است. Docker خودش تضمین نمی‌کند «latest» حتماً جدیدترین build زمانی باشد.

A tag gives us a readable label such as 1.0 or 1.1.3. But tags are generally mutable: a repository owner can point the same tag at different image content later. Two people pulling codenames-web:demo at different times may therefore get different content.

در مقابل، digest به محتوای مشخص اشاره می‌کند. اگر دقیقاً همان manifest را دوباره بخواهی، digest مرجع محکم‌تری است. قرار نیست از این لحظه همه‌جا digest بنویسی؛ فقط فرق را نگه دار: tag یک نام قابل‌حرکت است، digest هویت یک محتوای مشخص.

latest is also just a tag. If you omit a tag, Docker normally defaults to latest; that is a naming default, not a promise to discover the newest release. A latest tag can be old or absent.

registry برای هر محتوای منتشرشده digest از نوع sha256:… گزارش می‌کند. tag مثل نام متحرک روی قفسه است؛ digest مثل اثرانگشت دقیق همان manifest است. در image چندسکویی، digest ممکن است به manifest index اشاره کند که manifestهای هر معماری را کنار هم معرفی می‌کند؛ با IMAGE ID محلی یکی نیست.

A registry reports a sha256:… digest for published content. A tag is a movable label on a shelf; a digest is the exact content-addressed identity of the registry manifest. For a multi-platform image, the digest may identify an index that points to platform-specific manifests; it is not the same thing as a local IMAGE ID.

برای بیشتر تمرین‌ها و دستورهای انسانی tag نسخه‌دار کافی است. digest وقتی ارزش پیدا می‌کند که بخواهی دقیقاً همان خروجی ساخته‌شده را دوباره بگیری یا در گزارش بنویسی کدام محتوا آزمایش شده. digest می‌گوید «این همان محتواست»، نه «این محتوا امن یا مورداعتماد است». اعتبار ناشر، اسکن و امضای خروجی ساخته‌شده بحث‌های جدا هستند؛ login یا private بودن هم به‌تنهایی اعتماد را ثابت نمی‌کند.

A version tag is usually enough for everyday learning and readable commands. A digest matters when you need to retrieve exactly the same artifact or record precisely what was tested. A digest says “this is the same content,” not “this content is safe or trusted.” Publisher identity, scanning, and signatures are separate questions; login or repository privacy alone does not establish trust.

در تیم‌ها گاهی tagهایی مثل 1.1.3 را کنار شناسهٔ کوتاه commit مثل git-a1b2c3d هم می‌بینی. commit-tag کمک می‌کند image را به source وصل کنی، ولی اگر سیاست می‌خواهد خروجی ساخته‌شده تغییرناپذیر بماند digest را هم ثبت کن؛ اسم tag به‌تنهایی جلوی جابه‌جایی را نمی‌گیرد. لازم نیست برای این فصل وارد قواعد کامل SemVer شوی.

Teams sometimes publish a tag such as 1.1.3 alongside a commit-oriented tag such as git-a1b2c3d. A commit tag helps connect an image to source, but record the digest when you need exact artifact identity; the tag name alone does not prevent it from moving. This chapter does not require a full SemVer course.

قبل از push باید معلوم باشد چه کسی اجازهٔ نوشتن داردAuthenticate for access, then push

وقتی repository خصوصی است یا می‌خواهی چیزی منتشر کنی، registry باید هویتت را بشناسد. این مرحله را با خود push قاطی نکن. اگر login شکست می‌خورد، هنوز اصلاً به مسئلهٔ لایه‌ها و build نرسیده‌ای. اول دسترسی را درست کن، بعد سراغ انتشار برو.

Before the first push, make sure the repository exists and its visibility (public or private) is what you intend. Some services create repositories automatically and others do not; do not rely on that assumption.

در مثال‌های دوره هیچ رمز واقعی را داخل فرمان، Dockerfile یا فایل پروژه نمی‌گذاریم. اگر registry از token پشتیبانی می‌کند، از token با کمترین سطح دسترسی لازم استفاده کن و برای ورودی غیرتعاملی سراغ روش امنی مثل --password-stdin برو. هدف این فصل مدیریت سازمانی secret نیست؛ فقط نمی‌خواهیم برای یک push ساده، اعتبارنامه را بی‌دلیل در history پخش کنیم.

To push, the registry must know who you are and grant write access to that repository. The current Docker Hub CLI offers a built-in login flow. By default, docker login for Hub uses a device-code/browser flow: enter the one-time code on the official page without putting your account password in a command.

docker login

اگر registry دیگری داری، میزبان آن را به login بده؛ فقط نام میزبان و در صورت نیاز port را بنویس، نه مسیر repository. اگر registry از token پشتیبانی می‌کند، token محدود به کار لازم و دارای تاریخ انقضا بساز؛ آن را مثل رمز حساب نگه دار.

For another registry, pass its host to login—only the host and optional port, not a repository path. If it supports tokens, create a scoped token with an appropriate expiry and treat it like an account password.

docker login registry.example.net --username YOUR_USER
# Enter the token at Docker's password prompt; do not append it to this command.

در اسکریپت یا CI، token را از secret store همان محیط به ورودی استاندارد بده؛ token واقعی را نه در source و نه در فرمانِ ثبت‌شونده قرار نده:

In a script or CI job, pass the token from that environment’s secret store through standard input. Do not place a real token in source or in a recorded command:

printf '%s' "$REGISTRY_TOKEN" | docker login registry.example.net \
  --username "$REGISTRY_USER" --password-stdin

این الگو را فقط وقتی اجرا کن که REGISTRY_TOKEN از secret store تزریق شده و echo/log آن خاموش باشد؛ مقدار واقعی را مستقیم جای آن تایپ نکن. --password-stdin کمک می‌کند token در history خط فرمان نیاید. اگر اعتبارنامه helper/اعتبارنامه store سیستم‌عامل در دسترس است از آن استفاده کن؛ در برخی تنظیم‌ها Docker اعتبارنامه را در config.json نگه می‌دارد و base64 رمزنگاری نیست. دسترسی write به registry حساس است، اما login نه دسترسی‌های دیگر را امن می‌کند و نه خود image را بررسی می‌کند.

Use this pattern only when REGISTRY_TOKEN is injected by a secret store and shell tracing/logging is disabled; never type the real value directly in place of it. --password-stdin helps keep the token out of shell history. Prefer an operating-system credential helper/store when available; some Docker configurations store credentials in config.json, where base64 is not encryption. Registry write access is sensitive, but login does not secure other access or inspect the image itself.

خروجی push را بخوان؛ هر خط می‌گوید کدام لایه واقعاً منتقل شدRead push as shipping a package

حالا image نام درست دارد و دسترسی هم برقرار است. docker push را اجرا کن و فقط منتظر خط آخر نمان. خروجی لایه‌به‌لایه می‌گوید چه چیزی در حال ارسال است، چه چیزی قبلاً در registry وجود داشته و در پایان چه digestای برای محتوای منتشرشده ثبت شده است.

Now that the remote name and permission are clear, publish the local image. First verify the destination tag; then read the push output like a shipping receipt.

docker tag demo-web:1.0 YOUR_ACCOUNT/codenames-web:1.0
docker image ls YOUR_ACCOUNT/codenames-web
docker push YOUR_ACCOUNT/codenames-web:1.0

پیام‌هایی مثل Layer already exists خطا نیستند؛ اتفاقاً نشان می‌دهند registry لایهٔ یکسان را دوباره دریافت نکرده. image از چند لایه تشکیل شده و registry می‌تواند محتوای مشترک را reuse کند. این رفتار یکی از دلایلی است که push نسخه‌های نزدیک به هم معمولاً لازم نیست همهٔ بایت‌ها را از صفر بفرستد.

Exact output varies with the Docker version and layer count, but you may see a sequence like this. The short IDs below are illustrative and vary:

The push refers to repository [docker.io/YOUR_ACCOUNT/codenames-web]
2a71: Preparing
7c09: Waiting
2a71: Pushed
base-layer: Layer already exists
1.0: digest: sha256:8f...e31 size: 1572

Preparing یعنی Docker این layer را برای ارسال آماده می‌کند؛ Waiting یعنی نوبتش هنوز نرسیده؛ Pushed یعنی layer لازم منتقل شده؛ Layer already exists یعنی همان محتوای لایه از قبل در مقصد حاضر بوده و دوباره لازم نبوده ارسال شود. در پایان، registry برای tag digest می‌دهد. push همهٔ حجم image را هر بار دوباره نمی‌فرستد: layerهای محتوایی مشترک قابل‌بازاستفاده‌اند؛ metadata/manifest و tag هم باید در مقصد ثبت شوند.

Preparing means Docker is preparing a layer; Waiting means it has not uploaded yet; Pushed means the required layer was transferred; Layer already exists means the same layer content was already present remotely. At the end, the registry reports a digest for the tag. A push does not resend every byte each time: shared content-addressed layers can be reused, while the destination still records the manifest/metadata and tag.

خط digest را یادداشت کن؛ بعد در صفحهٔ repository هم ببین tag ظاهر شده باشد. موفقیت push به‌تنهایی هنوز ثابت نمی‌کند هم‌تیمی image را می‌تواند دریافت و اجرا کند؛ برای آن باید از سمت دریافت‌کننده آزمایش کنیم.

Record the digest line, then confirm the tag appears in the repository’s tag list. A successful push does not yet prove a teammate can retrieve and run the image; test from the receiving side.

حرف کافی نیست؛ نسخهٔ محلی را بردار و ثابت کن registry واقعاً منبع image شدهProve it: remove the local reference and retrieve it again

تا وقتی image محلی روی ماشینت مانده، اجرای موفق بعد از push چیز مهمی را ثابت نمی‌کند؛ Docker ممکن است همان نسخهٔ قبلی را استفاده کرده باشد. برای آزمایش واقعی، container مربوط به lab را جمع کن، image محلی را با دقت حذف کن و بعد همان نام کامل را pull کن.

If you only tagged the image and never pushed it, the remote-looking name exists only on your machine and your teammate sees nothing. A stronger proof is to remove the test container, remove every local name pointing to the image, verify they are absent, and then pull.

# Run this only after confirming demo-web is the disposable Chapter 4 container; otherwise skip.
docker rm -f demo-web
docker image rm YOUR_ACCOUNT/codenames-web:1.0 demo-web:1.0
docker image ls --digests YOUR_ACCOUNT/codenames-web
docker image ls demo-web

اگر docker rm گفت container وجود ندارد، خوب است؛ فرمان بعدی را فقط برای نام دقیق آزمایش اجرا کن. در دو فهرست آخر نباید آن tagها را ببینی. حالا محتوای راه‌دور را دریافت کن:

If docker rm says the container does not exist, that is fine; continue with the exact lab image names. The final listings should no longer show those tags. Now retrieve the remote content:

docker pull YOUR_ACCOUNT/codenames-web:1.0
docker image ls --digests YOUR_ACCOUNT/codenames-web
docker image inspect YOUR_ACCOUNT/codenames-web:1.0 --format '{{.Id}} {{json .RepoDigests}}'

حالا tag دوباره در store محلی حاضر است و RepoDigests باید مرجع registry و digest را نشان دهد. اگر pull از cache layerها را بازاستفاده کرد، باز هم منبع این tag در فرمان registry بوده است؛ نبودن tag پیش از pull و ظاهرشدنش بعد از آن مدرک مهم‌تری از حجم دانلود است. برای اثبات نهایی، container را اجرا و از میزبان درخواست بفرست.

The tag is now back in the local store, and RepoDigests should show the registry reference and digest. Even if pull reuses cached layers, the source of this reference was the registry. Its absence before the pull and presence afterward matter more than how many bytes were downloaded. For final proof, run it and make a host request.

برای دریافت دقیق همان محتوا، digest کامل واقعی را از خروجی push یا RepoDigests کپی کن و به‌جای placeholder بگذار. رشتهٔ نمایشی زیر را عیناً اجرا نکن:

To retrieve exactly that content, copy the complete real digest from the push output or RepoDigests and replace the placeholder below. Do not run the illustrative token literally:

docker pull YOUR_ACCOUNT/codenames-web@sha256:PASTE_REAL_DIGEST_HERE

این شکل repository@digest است، نه repository:tag@digest. tag برای انتخاب انسان‌خوان است؛ digest محتوای دقیق را مشخص می‌کند. اگر digest متعلق به index چندسکویی باشد، Docker manifest سازگار با platform خودش را انتخاب می‌کند.

The form is repository@digest, not repository:tag@digest. The tag is a readable selection; the digest identifies exact content. If it identifies a multi-platform index, Docker selects the manifest for its platform.

docker run -d --name registry-proof -p 8080:3000 YOUR_ACCOUNT/codenames-web:1.0
docker ps --filter name=registry-proof
docker inspect registry-proof --format '{{.Config.Image}} → {{.Image}}'
curl --fail http://localhost:8080

در inspect، مقدار اول نامی است که به container داده‌ای و مقدار دوم شناسهٔ image محلیِ استفاده‌شده است. پاسخ hello from CodeNames نشان می‌دهد image دریافت‌شده فرایند برنامه را اجرا کرده و درخواست از port میزبان به آن رسیده است. این آزمایش ثابت می‌کند image قابل‌انتقال است؛ هنوز امنیت، سازگاری معماری دیگر یا کیفیت برنامه را ثابت نمی‌کند.

In inspect, the first value is the name used to create the container and the second is the local image ID it uses. The hello from CodeNames response proves the retrieved image started the app process and the request reached it through the host port. This demonstrates distribution and execution—not security, compatibility with every architecture, or application quality.

وقتی push یا pull می‌شکند، اول ببین مشکل نام است، دسترسی است یا اصلاً نسخه منتشر نشدهWhen push or pull fails, isolate the boundary

خطاهای registry خیلی وقت‌ها شبیه هم دیده می‌شوند، اما از یک جا نمی‌آیند. قبل از rebuild یا login دوباره، نام کامل image را بخوان: registry، namespace، repository و tag درست‌اند؟ بعد دسترسی را بررسی کن. در آخر بپرس آیا همان tag واقعاً push شده است یا فقط روی لپ‌تاپ تو وجود دارد.

Registry errors can look alike while coming from different boundaries: destination naming, permission, selected tag, or network connectivity. Before logging in again or rebuilding, ask which boundary lacks evidence.

۱۸ تمرین؛ هر بار مشخص کن «این image الان کجاست؟»18 exercises: from names to remote evidence

قبل از بازکردن پاسخ، برای هر سناریو یک جمله بنویس: image روی کدام ماشین یا registry وجود دارد، با چه نامی، و هنوز چه چیزی ثابت نشده؟ بعضی سؤال‌ها فقط دربارهٔ نام‌گذاری‌اند؛ بعضی از تو می‌خواهند فرق tag، digest و انتشار واقعی را از روی نشانه‌ها توضیح بدهی.

Before opening each solution, write down a prediction and one piece of evidence. Some prompts ask only for a correct reference; others ask what remains unproven.

آزمایشگاه: image را از لپ‌تاپت بیرون بفرست و دوباره از صفر برگردانLab: publish, remove, and retrieve the image

۱. وضعیت پایه و tag نسخه‌دار1. Establish the baseline and a version tag

در نیمهٔ دوم آزمایش یک tag ناموجود را عمداً pull می‌کنیم. هدف این نیست که خطا بسازیم و رد شویم؛ می‌خواهیم از متن خطا تشخیص بدهیم «احراز هویت خراب است» با «این tag اصلاً وجود ندارد» چه فرقی دارد.

From the project root, enter demo-web. Confirm the app and previous build; if the Chapter 4 image is absent, build it as version 1.0. Replace the account placeholder in the tag—do not run it literally.

cd demo-web
docker image ls demo-web
docker build -t demo-web:1.0 .
docker tag demo-web:1.0 YOUR_ACCOUNT/codenames-web:1.0
docker image ls --digests YOUR_ACCOUNT/codenames-web

دو tag باید image ID یکسان داشته باشند. این نقطهٔ شروع محلی است؛ هنوز repository راه‌دور را آماده یا image را ارسال نکرده‌ای.

The two tags should share an image ID. This is the local starting point; the remote repository has not yet received anything.

۲. login امن و push2. Authenticate safely and push

برای Docker Hub فرمان docker login را اجرا کن و جریان device-code را در مرورگر کامل کن. برای registry دیگر، login را به میزبان محدود کن و اگر token لازم است آن را در prompt وارد کن. هیچ رمز یا token واقعی را در Dockerfile، فایل مثال، shell دستور قابل‌ثبت یا اسکرین‌شات نگذار.

For Docker Hub, run docker login and complete the device-code flow in a browser. For another registry, log in to its host and enter a token only at the prompt if required. Never put a real credential in a Dockerfile, example file, recorded shell command, or screenshot.

docker login
docker push YOUR_ACCOUNT/codenames-web:1.0

در خروجی پایان‌یافته tag و digest را ثبت کن. چند خط Layer already exists طبیعی است. وارد registry UI شو و بررسی کن repository و tag واقعاً دیده می‌شوند؛ این، محلی image ls نیست.

Record the completed tag and digest. Layer already exists is normal. Open the registry UI and confirm the repository and tag are present; that is different evidence from local image ls.

۳. تصویر محلی را حذف کن؛ بعد دوباره دریافتش کن3. Remove the local copy, then retrieve it again

اگر container قدیمی با نام demo-web داری، پیش از حذف image با docker inspect بررسی کن همان تمرین stateless فصل ۴ است؛ فقط همان object را حذف کن. بعد هر دو نام محلی را بردار. اگر Docker گفت image هنوز استفاده می‌شود، فهرست containerها را بخوان؛ سراغ prune -a نرو.

If an old container named demo-web exists, use docker inspect to confirm it is the stateless Chapter 4 exercise before removing that specific object. Then remove both local names. If Docker says the image is still in use, inspect containers; do not reach for prune -a.

# Run only after confirming demo-web is the disposable Chapter 4 container; otherwise skip.
docker rm -f demo-web
docker image rm YOUR_ACCOUNT/codenames-web:1.0 demo-web:1.0
docker image ls YOUR_ACCOUNT/codenames-web
docker image ls demo-web
docker pull YOUR_ACCOUNT/codenames-web:1.0
docker image ls --digests YOUR_ACCOUNT/codenames-web
docker image inspect YOUR_ACCOUNT/codenames-web:1.0 --format '{{.Id}} {{json .RepoDigests}}'

ثبت کن: قبل از pull چه tagهایی نبودند و بعد از pull کدام tag و RepoDigest ظاهر شد. اگر layerها سریع برگشتند یا پیام دانلود کم بود، ممکن است Docker cache مشترک را reuse کرده باشد؛ معیار، نبودن نام قبل و resolve شدن راه‌دور reference بعد است.

Record which tags were absent before the pull and which tag/RepoDigest appeared afterward. If layers return quickly or little data downloads, Docker may have reused shared cache. The evidence is absence before and successful remote resolution afterward.

حالا tag محلی را بردار تا اجرای بعدی حتماً از reference digest resolve شود. digest کامل را با مقدار واقعی خروجی خودت جایگزین کن:

Now remove the local tag so the next run resolves through the digest reference. Replace the digest with the complete value from your own output:

docker image rm YOUR_ACCOUNT/codenames-web:1.0
docker pull YOUR_ACCOUNT/codenames-web@sha256:PASTE_REAL_DIGEST_HERE
docker run -d --name registry-digest-proof -p 8080:3000 \
  YOUR_ACCOUNT/codenames-web@sha256:PASTE_REAL_DIGEST_HERE
curl --fail http://localhost:8080

اگر pull و run موفق شد، همان خروجی ساخته‌شده با شناسهٔ محتوایی دقیق دریافت و اجرا شده است. نگه‌داشتن digest و tag کنار هم مفید است: digest دقت می‌دهد و tag خوانایی. image محلی alias ممکن است بعد از pull digest به شکل tag ظاهر شود یا نه، پس برای این آزمایش به خروجی خود pull/inspect توجه کن، نه به فرض دربارهٔ نام‌های محلی.

If pull and run succeed, the exact content-addressed artifact was retrieved and executed. Keeping both tag and digest is useful: the digest gives precision and the tag gives readability. Local aliases after a digest pull can vary, so read the actual pull/inspect output instead of assuming a particular local name.

۴. container را از image pullشده اجرا کن4. Run a container from the pulled image

docker run -d --name registry-proof -p 8080:3000 YOUR_ACCOUNT/codenames-web:1.0
docker ps --filter name=registry-proof
docker inspect registry-proof --format '{{.Config.Image}} {{.Image}}'
curl --fail http://localhost:8080

باید پاسخ hello from CodeNames ببینی. نام image تنظیم‌شده در container را کنار شناسهٔ image استفاده‌شده ثبت کن. حالا شاهد داری که tag راه‌دور دوباره به store محلی آمده، از آن container ساخته شده و مسیر HTTP کار کرده است.

You should see hello from CodeNames. Record the configured image name and the image ID used by the container. This shows that the remote tag returned to the local store, created a container, and served an HTTP request.

۵. نسخهٔ دوم بساز و دو هویت را مقایسه کن5. Publish a second version and compare identities

container را جمع کن. متن پاسخ در server.js را اندکی عوض کن، مثلاً hello from CodeNames v1.1؛ این تغییر باید در source باشد تا build واقعاً محتوای تازه بسازد. نسخهٔ دوم را با tag تازه push کن، نه اینکه 1.0 را بی‌صدا جایگزین کنی.

Remove the lab container. Change the response text in server.js, for example to hello from CodeNames v1.1. The source change ensures a new build has different content. Push a new tag instead of silently replacing 1.0.

docker rm -f registry-proof registry-digest-proof
docker build -t demo-web:1.1 .
docker tag demo-web:1.1 YOUR_ACCOUNT/codenames-web:1.1
docker push YOUR_ACCOUNT/codenames-web:1.1
docker image ls --digests YOUR_ACCOUNT/codenames-web

معمولاً digest نسخهٔ 1.1 با digest ثبت‌شده برای 1.0 فرق می‌کند چون محتوا عوض شده. برای یک آزمایش جدا و فقط در repository/tag آزمایشی، می‌توانی هر دو build را پشت tag متحرک demo push کنی و ببینی همان tag به digest تازه رسیده است؛ این کار را روی release tag یا repository با immutable-tag policy انجام نده. ثبت version tag و digest هر دو، جابه‌جایی را قابل‌مشاهده می‌کند.

The 1.1 digest should normally differ from 1.0 because the content changed. In a separate disposable experiment, you can push both builds under a movable demo tag and observe the tag resolve to a new digest; do not do this with a release tag or a repository enforcing immutable tags. Recording both version tags and digests makes the change visible.

۶. یک خطا تشخیصی بساز و مدرک را بخوان6. Create one diagnostic failure and read the evidence

از tagی استفاده کن که می‌دانی وجود ندارد. اگر repository عمومی است هم درخواست pull باید نشان دهد tag پیدا نشد؛ اگر private است ممکن است registry برای نام ناموجود و مجوز ناکافی پیام مشابه بدهد، پس علت را فقط از یک متن خطا حدس نزن.

Request a tag you know does not exist. A public repository should report a missing tag; a private registry may give a similar message for a missing name and insufficient access, so do not infer the cause from one error string alone.

docker pull YOUR_ACCOUNT/codenames-web:99.99-not-published
docker image ls --digests YOUR_ACCOUNT/codenames-web

خطای موردانتظار، unknown/not found tag است؛ فهرست registry را با tagهای 1.0 و 1.1 مقایسه کن. repair برای اجرای نسخهٔ پایدار، pull کردن tag موجود است؛ در این drill، rebuild راه‌حل نیست چون مقصد عمداً وجود ندارد.

Expect an unknown/not-found tag. Compare the registry listing with 1.0 and 1.1. To run a known release, pull an existing tag; rebuilding is not the fix because the requested remote reference was intentionally absent.

۷. پیش از پاک‌سازی، گزارش کوتاه بساز7. Record evidence before cleanup

گزارشت باید نام کامل repository، tagهای منتشرشده، digest هر push، نتیجهٔ pull پس از حذف محلی، پاسخ curl، و علت شکست tag ناموجود را داشته باشد. اعتبارنامه‌ها و token نباید در گزارش باشند.

Your handoff should include the full repository name, published tags, each push digest, pull-after-removal evidence, the curl response, and the diagnosis for the missing tag. Do not include credentials or tokens.

docker rm -f registry-proof registry-digest-proof
docker image rm YOUR_ACCOUNT/codenames-web:1.0 YOUR_ACCOUNT/codenames-web:1.1 \
  demo-web:1.0 demo-web:1.1

این پاک‌سازی فقط container و چهار tag همین آزمایش را هدف می‌گیرد؛ repository راه‌دور را حذف نمی‌کند. اگر imageها به container دیگری وصل‌اند، Docker حذف را رد می‌کند؛ آن مصرف‌کننده را شناسایی کن و بدون بررسی داده‌اش پاکش نکن. imageهای مشترک base ممکن است به‌خاطر مصرف پروژه‌های دیگر روی ماشین بمانند.

This cleanup targets only the lab container and its four tags; it does not delete the remote repository. If another container uses an image, Docker may refuse removal. Identify that consumer and do not delete it without checking its data. Shared base images may remain because other projects use them.

مرجع سریع؛ هر دستور کدام مرز را طی می‌کند؟Quick reference: which boundary does each command cross?

مستند رسمی docker image tag قالب مرجع image و پیش‌فرض‌ها را توضیح می‌دهد؛ docker login جریان device-code، اعتبارنامه store و --password-stdin را دارد؛ راهنمای Push در Docker Hub و docker image push رفتار ارسال را نشان می‌دهند. برای digest و pull هم مرجع docker image pull و docker image ls --digests را ببین. رفتار پیش‌فرض Hub یا امکانات UI ممکن است تغییر کند؛ پیش از آموزش آن‌ها، مستند رسمی را دوباره بررسی کن.

The official docker image tag reference explains image-reference syntax and defaults. docker login documents device-code flow, credential stores, and --password-stdin. The Docker Hub push guide and docker image push explain publication behavior. For digests and retrieval, see docker image pull and docker image ls --digests. Hub defaults and UI features can change; recheck the official docs before teaching them.