وقتی docker ps می‌زنیم، پشت صحنه چه اتفاقی می‌افتد؟When we say “Docker is installed,” what exactly was installed?

فرض کن Docker را تازه نصب کرده‌ای. آیکن Desktop سبز است و همه‌چیز ظاهراً خوب به نظر می‌رسد. وارد ترمینال می‌شوی، docker ps را می‌زنی و خطا می‌گیری. اولین وسوسه این است که بگویی «پس Docker درست نصب نشده». اما هنوز برای چنین نتیجه‌ای زود است. شاید خود CLI سالم باشد و فقط نتواند به Docker Engine برسد. برای همین اول باید مسیر این دستور را بشناسیم.

In Chapter 1, Docker was a way to package and run reproducible environments. Now we need to separate the moving parts. When you type docker ps, the terminal itself knows nothing about containers. A client program called the Docker CLI runs, connects to an endpoint, and asks the Docker Engine for state.

از کجا بفهمیم دقیقاً کدام بخش سالم است؟Four commands that prove four different things

اینجا چهار دستور داریم که ظاهرشان شبیه هم است، ولی هرکدام چیز متفاوتی را به ما نشان می‌دهند. اگر فرقشان را بفهمی، بعداً به‌جای نصب دوباره و حدس‌زدن، با چند دستور ساده می‌فهمی مشکل از کجاست.

Many bad troubleshooting sessions begin with “Docker is installed because version works.” A better question is: which version command, and what exactly did it prove?

docker --version
docker version
docker context show
docker info --format 'server={{.ServerVersion}} root={{.DockerRootDir}}'
docker ps

Docker version 29.x, build 1234567

Client: Docker Engine - Community
 Version:           29.x
 Context:           default
Server: Docker Engine - Community
 Engine:
  Version:          29.x

default
server=29.x root=/var/lib/docker

CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES

خالی بودن جدول docker ps خطا نیست؛ فقط یعنی running container نداریم. این تفاوت کوچک مهم است: دستور موفق بوده و Engine جواب داده، حتی اگر نتیجهٔ پرس‌وجو صفر ردیف باشد.

An empty docker ps table is not a failure; it simply means there are no running containers. The command still succeeded and the Engine answered even though the query returned zero rows.

یک بار موتور Docker را خاموش کنیم و نتیجه را ببینیمStop the daemon deliberately to see the Client/Server boundary

بهترین راه برای فهمیدن مرز بین CLI و Engine این است که آن را عمداً خراب کنیم. روی یک سیستم آزمایشی Linux، daemon را متوقف می‌کنیم و قبل از اجرای هر دستور حدس می‌زنیم کدام‌یک هنوز باید کار کند. بعد خروجی را با حدسمان مقایسه می‌کنیم.

On a learning Linux machine, one of the best ways to understand the architecture is to deliberately remove one layer. Before running anything, predict which commands should still work and which should fail.

sudo systemctl stop docker

docker --version
docker version
docker info
docker ps

sudo systemctl start docker

Docker version 29.x, build 1234567

Client: Docker Engine - Community
 Version:           29.x
 Context:           default
Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

این خروجی معماری را بهتر از تعریف حفظی نشان می‌دهد. docker --version اصلاً سرور را لمس نکرد. docker version توانست کلاینت محلی را بخواند ولی وقتی به سرور رسید ناموفق شد. info و ps بدون Engine پاسخ مفیدی ندارند.

This output teaches the architecture better than a memorized definition. docker --version never touched the Server. docker version could read the local Client but failed when it reached the Server. info and ps depend on an Engine response.

Docker Engine با Docker Desktop چه فرقی دارد؟Docker Engine and Docker Desktop are not the same thing

این دو اسم زیاد کنار هم می‌آیند و برای همین راحت قاطی می‌شوند. Docker Engine همان بخشی است که واقعاً image و container را مدیریت می‌کند. Docker Desktop یک محیط کامل‌تر برای توسعه است که همین Engine را همراه با رابط کاربری، تنظیم منابع و اتصال به محیط‌هایی مثل WSL در اختیارمان می‌گذارد.

Docker Engine is the server-side system that manages the API, daemon, runtime stack, images, and containers. Docker Desktop is a broader developer product that packages an Engine with integration, UI, resource management, updates, and development tooling.

نصب روی Ubuntu؛ هر دستور برای چه کاری است؟Ubuntu: do not see a command wall; understand the trust and package chain

اگر دستورهای نصب را فقط کپی کنی، دفعهٔ بعد که یکی از آن‌ها خطا بدهد نمی‌دانی باید کجا را نگاه کنی. پس به‌جای یک دیوار بلند از دستورها، نصب را به سه سؤال ساده می‌شکنیم: بسته‌ها را از کجا می‌گیریم؟ از کجا مطمئن می‌شویم منبع قابل‌اعتماد است؟ و در آخر دقیقاً چه چیزهایی نصب می‌شوند؟

The standard maintainable path is Docker’s official APT repository. The idea is simple: APT needs to know where packages come from, which key validates that source metadata, and which packages to install.

sudo apt update
sudo apt install ca-certificates curl

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

URIs کد برنامه رسمی را مشخص می‌کند؛ Suites release فعلی Ubuntu را انتخاب می‌کند؛ Architectures معماری سیستم میزبان را می‌گیرد؛ و Signed-By می‌گوید فراداده این کد برنامه باید با همین key بررسی شود. این بخش security theater نیست؛ زنجیره of اعتماد package manager است.

URIs names the official source; Suites selects the current Ubuntu release; Architectures records host architecture; and Signed-By limits validation of this source to that key. This is not ceremony; it is the package manager’s trust chain.

sudo apt install \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

sudo systemctl status docker
sudo systemctl start docker   # only if it is not running

docker version
docker info
sudo docker run hello-world

اگر docker version فقط کلاینت را نشان داد، نصب CLI موفق بوده ولی هنوز سرور را ثابت نکرده‌ای. اگر sudo docker run hello-world موفق شد اما بدون sudo دسترسی denied گرفتی، دیگر مسئله installation نیست؛ مسئلهٔ دسترسی به سوکت است.

If docker version shows only Client information, the CLI installation succeeded but the Server is not yet proven. If sudo docker run hello-world works while the non-sudo command gets permission denied, the problem is no longer installation; it is socket access.

چرا با sudo کار می‌کند ولی بدون آن نه؟/var/run/docker.sock: a permission error can tell you a lot

این یکی از خطاهایی است که در نگاه اول آدم را به اشتباه می‌اندازد. ممکن است CLI نصب باشد، daemon هم روشن باشد، ولی کاربر فعلی اجازهٔ دسترسی به سوکتی را نداشته باشد که CLI از طریق آن با Docker حرف می‌زند. پس اینجا مسئله «نصب خراب» نیست؛ مسئله «اجازهٔ دسترسی» است.

On a typical Linux Docker Engine setup, the local CLI commonly talks to the daemon through a Unix socket. If the user cannot access that socket, the CLI may be perfectly healthy and the daemon may be running, yet the request still fails at the permission boundary.

docker ps
sudo docker ps
ls -l /var/run/docker.sock
id

permission denied while trying to connect to the Docker daemon socket

# sudo docker ps succeeds

srw-rw---- 1 root docker ... /var/run/docker.sock
uid=1000/alex gid=1000/alex groups=1000/alex,...

این مقایسه خیلی مهم‌تر از نصب دوباره کردن Docker است. اگر دستور معمولی دسترسی denied بدهد ولی همان دستور با sudo جواب بدهد، daemon و سوکت به‌احتمال زیاد حاضرند؛ credential کاربر معمولی اجازهٔ استفاده از سوکت را ندارد.

This comparison is far more informative than reinstalling Docker. If the ordinary command gets permission denied but the same command works with sudo, the daemon and socket are likely present; the ordinary user simply lacks socket access.

sudo usermod -aG docker $USER
# sign out and back in, or start a new session
id
docker ps

روی Windows، Linux container از کجا Linux می‌آورد؟Why Windows needs a Linux kernel for Linux containers

اگر container لینوکسی اجرا می‌کنیم، یک سؤال طبیعی پیش می‌آید: روی Windows که هستهٔ Linux نداریم، این container دقیقاً روی چه چیزی اجرا می‌شود؟ پاسخ را باید در WSL2 پیدا کنیم. WSL2 یک هستهٔ واقعی Linux در اختیار Windows می‌گذارد و Docker Desktop از همین بستر برای اجرای containerهای لینوکسی استفاده می‌کند.

Linux containers rely on Linux-kernel system calls and isolation features. The Windows kernel does not natively provide the same interface. WSL2 matters because it supplies a real managed Linux kernel that Docker Desktop can use for its Linux-container backend.

PowerShell و Ubuntu دو راه جدا برای رسیدن به یک Docker هستندPowerShell and Ubuntu/WSL are two client paths, not one magical route

فرض کن در PowerShell دستور docker ps کاملاً کار می‌کند، اما همان دستور داخل Ubuntu خطا می‌دهد. این عجیب نیست. PowerShell و Ubuntu دو محیط جدا هستند و هرکدام CLI و مسیر اتصال خودشان را دارند. ممکن است هر دو در نهایت به همان Docker Engine برسند، اما راه رسیدنشان یکی نیست.

This is where a misleading diagram can do more damage than a weak paragraph. The Windows CLI and the Linux CLI inside Ubuntu are different executables in different environments. Both can reach Docker Desktop’s backend, but they do not follow an identical path. WSL Integration matters for the Linux distribution’s access; PowerShell should not be modeled as passing through a generic “WSL Integration layer.”

wsl --version
wsl -l -v

در wsl -l -v ستون نسخه برای توزیع مورد استفاده باید 2 باشد. Running یا Stopped وضعیت فعلی توزیع است؛ با WSL نسخه یکی نیست.

In wsl -l -v, the VERSION column should show 2 for the distribution you intend to integrate. Running or Stopped is the distro’s current state, not its WSL architecture version.

از کجا مطمئن شویم هر دو ترمینال همان Engine را می‌بینند؟How do we prove PowerShell and Ubuntu are really seeing the same Engine?

فقط اینکه هر دو جا یک شماره نسخه ببینی کافی نیست. دو Engine جدا هم می‌توانند دقیقاً یک نسخه داشته باشند. راه مطمئن‌تر این است که در یکی از ترمینال‌ها چیزی بسازیم و در دیگری همان مورد را با همان شناسه پیدا کنیم. اگر این اتفاق افتاد، دیگر فقط به شباهت خروجی‌ها تکیه نکرده‌ایم.

Matching Server Version strings are not conclusive proof. Two independent Engines can run the same version. A stronger test is to create shared state on one side and observe that exact object from the other.

docker context show
docker info --format 'name={{.Name}} root={{.DockerRootDir}} server={{.ServerVersion}}'
docker run -d --name engine-proof nginx:alpine
docker inspect engine-proof --format '{{.Id}}'

docker context show
docker info --format 'name={{.Name}} root={{.DockerRootDir}} server={{.ServerVersion}}'
docker ps --filter name=engine-proof
docker inspect engine-proof --format '{{.Id}}'

اگر همان container name و همان container شناسه را از هر دو طرف می‌بینی، مدرک خیلی قوی‌تری داری که هر دو کلاینت به یک Docker وضعیت رسیده‌اند. بعد از آزمایش:

If both sides see the same container name and the same container ID, you have much stronger evidence that both clients reached the same Docker state. Clean up afterward:

docker rm -f engine-proof

hello-world فقط پیام تبریک نیستDo not treat hello-world as a congratulation message; read its trace

اولین بار که hello-world را اجرا می‌کنی، Docker چند کار را پشت سر هم انجام می‌دهد: image را پیدا می‌کند، اگر لازم باشد آن را می‌گیرد، container را می‌سازد، اجرا می‌کند، خروجی را نشان می‌دهد و پایان پردازش را ثبت می‌کند. پس همین مثال کوچک در واقع یک آزمایش کامل برای مسیر اجراست.

If the image is absent locally, the first docker run hello-world exercises several stages: local lookup, pull if needed, create, start, stdout, and exit. If a second run does not pull, that does not invalidate the test; the image is probably already in the local store.

docker run hello-world
docker ps
docker ps -a --filter ancestor=hello-world

در فصل بعد همین اتفاق را آهسته‌تر باز می‌کنیم: چرا container در ps نیست ولی در ps -a دیده می‌شود، و چه چیزی باعث توقف آن شد.

Chapter 3 will slow this down: why the container disappears from ps yet remains in ps -a, and what caused it to stop.

وقتی خطا می‌بینی، از کجا شروع کنی؟Troubleshooting means naming the broken layer before choosing a fix

فرض کن فقط این جمله را می‌شنوی: «Docker کار نمی‌کند.» این هنوز هیچ چیزی به ما نمی‌گوید. باید خطا را مرحله‌به‌مرحله کوچک کنیم: آیا دستور docker پیدا می‌شود؟ آیا CLI به Engine وصل می‌شود؟ آیا مشکل دسترسی داریم؟ آیا روی Windows، WSL درست به Desktop متصل شده؟ هر جواب، چند احتمال را کنار می‌زند.

An error string is not a complete diagnosis; it is an observation. A strong flow is: symptom → suspected layer → diagnostic command → fix → verification.

شش دام که ظاهرشان شبیه «Docker خراب است» استSix traps that all look like “Docker is broken”

روی Ubuntu فقط دنبال کلمهٔ active نگردDo not stop at “systemd is green”; read what the service status tells you

وقتی روی Ubuntu می‌خواهی ببینی daemon واقعاً بالا آمده یا نه، systemctl status docker مثل یک برگهٔ وضعیت کوتاه است. فقط به سبز بودن active نگاه نکن؛ همان چند خط به تو می‌گوید سرویس شناخته شده یا نه، الآن در چه وضعیتی است و پردازش اصلی‌اش کدام است.

On a typical Ubuntu host, systemctl status docker is one of the best places to see whether the daemon became a running process at all. But if you only look for the word active, you throw away most of the useful evidence.

sudo systemctl status docker --no-pager

● docker.service - Docker Application Container Engine
     Loaded: loaded (...; enabled; preset: enabled)
     Active: active (running) since ...
   Main PID: 2148 (dockerd)
      Tasks: ...
     Memory: ...
        CPU: ...
     CGroup: /system.slice/docker.service
             └─2148 /usr/bin/dockerd -H fd:// ...

Loaded می‌گوید unit شناخته شده است؛ enabled بیشتر دربارهٔ boot/راه‌اندازی سیاست است، نه اینکه همین لحظه پردازش سالم باشد. Active: active (running) وضعیت فعلی را می‌دهد و Main PID نشان می‌دهد systemd کدام پردازش را daemon اصلی می‌داند.

Loaded says the unit is known; enabled is mainly about boot/start policy, not proof that a healthy process exists right now. Active: active (running) gives current state, and Main PID identifies the daemon process systemd is managing.

اگر وضعیت برابر ناموفق باشد، فقط راه‌اندازی دوباره نزن. اول logهای نزدیک خطا را بخوان:

If status is failed, do not immediately restart and erase the moment. Read recent service logs first:

sudo journalctl -u docker -n 60 --no-pager

هدف این نیست که تمام logهای dockerd را بلد باشی؛ دنبال اولین خطا معناداری بگرد که زنجیره خطا را شروع کرده. ده خط بعدی ممکن است فقط پیامد همان خط اول باشند.

You do not need to memorize every dockerd log message. Look for the first meaningful error that began the failure chain; many later lines may be consequences rather than the cause.

گاهی Docker خراب نیست؛ فقط داری با Engine اشتباهی حرف می‌زنیDocker context: when the command is correct but the target Engine is wrong

فرض کن دیروز یک image ساخته‌ای و امروز هرچه docker image ls می‌زنی پیدایش نمی‌کنی. قبل از اینکه دوباره build کنی، یک احتمال ساده را بررسی کن: شاید CLI امروز به Engine دیگری وصل است. در این حالت چیزی گم نشده؛ فقط مقصد دستورهایت عوض شده.

Sometimes nothing is actually broken. The CLI works, the daemon works, but the CLI is pointed at a different Engine. This matters especially with Desktop, remote Engines, or multiple installations.

docker context ls
docker context show
docker info --format \
'name={{.Name}} root={{.DockerRootDir}} server={{.ServerVersion}}'

این اتفاق وقتی چند context، Docker Desktop یا یک Engine راه‌دور داری کاملاً ممکن است. پس قبل از هر نصب دوباره یا build دوباره، اول ببین CLI واقعاً به کجا وصل شده است.

Suppose you built an image while context A was active. Later the active context becomes B and docker image ls no longer shows it. A weak response is to pull/build again. A better response is to verify the destination first; duplicating the artifact can merely hide a targeting mistake.

روی Windows هر دو سمت را جدا امتحان کنOn Windows, one green check is not enough; verify each client path separately

سبز بودن Docker Desktop فقط می‌گوید خود Desktop ظاهراً بالا است. هنوز معلوم نیست PowerShell و Ubuntu هر دو بتوانند از مسیر خودشان به آن برسند. برای همین هر محیطی را که واقعاً با آن کار می‌کنی جدا بررسی کن.

Docker Desktop can be Running and PowerShell fully functional while the Ubuntu/WSL client path is still broken. The reverse can also happen. Verify every environment you actually plan to use for development.

wsl -l -v
docker context show
docker version
docker info --format 'server={{.ServerVersion}}'

command -v docker
docker context show
docker version
docker info --format 'server={{.ServerVersion}}'

اول در PowerShell مطمئن شو CLI و Engine همدیگر را می‌بینند. بعد همان بررسی را داخل Ubuntu انجام بده. اگر هر دو سالم بودند، تازه می‌توانیم با یک container مشترک بررسی کنیم که واقعاً به یک Engine وصل‌اند.

These checks answer two different questions: does the Windows CLI path work, and does the Linux-distro CLI path work? If both do, the shared-state test can then prove whether they converge on the same Engine.

چرا «Desktop باز است» مدرک کافی نیست؟

Why is “Desktop is open” insufficient evidence?

چون UI وضعیت فقط یک بخش از زنجیره را می‌بیند. شل ممکن است Docker CLI را پیدا نکند؛ توزیع ممکن است WSL1 باشد؛ یکپارچه‌سازی ممکن است برای توزیع دیگری فعال باشد؛ یا context CLI به مقصد دیگری اشاره کند. عیب‌یابی خوب دقیقاً همین مرزها را جدا می‌کند.

Because UI status observes only part of the chain. The shell may not find a Docker CLI, the distro may be WSL1, integration may be enabled for another distro, or the CLI context may target something else. Good troubleshooting separates these boundaries.

یک نمونهٔ واقعی: PowerShell کار می‌کند، Ubuntu نهCase study: “it works in PowerShell, not in Ubuntu”

فرض کن همکارت می‌گوید: «Docker Desktop بازه، توی PowerShell همه‌چی کار می‌کنه، ولی توی Ubuntu هرچی docker ps می‌زنم خطا می‌گیرم.» اینجا اگر بی‌درنگ Docker را داخل Ubuntu نصب کنیم، ممکن است فقط مسئله را پیچیده‌تر کنیم. اول قدم‌به‌قدم می‌بینیم مسیر Ubuntu کجا قطع شده.

Treat this like a real support ticket. The initial report is only: “Docker Desktop is running. docker ps works in PowerShell. Ubuntu fails.” Do not fix yet; narrow the chain first.

wsl -l -v

NAME      STATE     VERSION
Ubuntu    Running   2

نسخه=2 یک احتمال را حذف می‌کند: مشکل «این توزیع هنوز WSL1 است» نیست.

VERSION=2 removes one hypothesis: this is not a “the distro is still WSL1” problem.

command -v docker
/usr/bin/docker

docker --version
Docker version 29.x, build ...

پس شل و کلاینت فایل اجرایی سالم‌اند. اگر خطا هنوز Cannot connect... است، دیگر مسیر را دست‌کاری نمی‌کنیم؛ یک لایه پایین‌تر می‌رویم.

So the shell and Client executable are healthy. If the error is still Cannot connect..., PATH is no longer our target; move one boundary deeper.

docker context show
docker info

# then verify Docker Desktop:
# Settings → Resources → WSL Integration → Ubuntu enabled

اگر یکپارچه‌سازی برای Ubuntu خاموش بوده و با فعال‌کردنش docker info سرور اطلاعات می‌دهد، راه‌حل و تشخیص با هم جورند: Linux کلاینت مسیر به بخش پشتی وصل نبود. لازم نبود Engine را داخل Ubuntu نصب کنیم.

If Ubuntu integration was disabled and enabling it makes docker info return Server facts, the fix matches the diagnosis: the Linux client path was not connected to the backend. Installing another Engine inside Ubuntu was unnecessary.

مرحلهٔ آخر مشترک-وضعیت آزمایش است. از PowerShell engine-proof را بساز و از Ubuntu همان شناسه را ببین. حالا گزارش فقط «درست شد» نیست؛ می‌گوید چه لایه‌ای خراب بود و چه چیزی recovery را ثابت کرد.

The final step is the shared-state test. Create engine-proof from PowerShell and observe the same ID from Ubuntu. The report is no longer “it works now”; it explains which boundary failed and what proved recovery.

۱۸ تمرین؛ این‌بار جواب را از روی نشانه‌ها پیدا کن18 exercises: from “is it installed?” to “which layer failed?”

قبل از اینکه پاسخ هر تمرین را باز کنی، یک حدس کوتاه بزن و بگو با کدام دستور می‌خواهی آن را بررسی کنی. قرار نیست فقط اسم دستورها را حفظ کنیم؛ می‌خواهیم از روی چیزی که می‌بینیم بفهمیم مشکل کجاست.

The final exercises deliberately preserve the same depth as the beginning of the chapter. Before revealing a solution, write a prediction or hypothesis.

آزمایشگاه: ثابت کن سیستم واقعاً برای کار آماده استLab: prove the machine is ready, not merely that Docker is installed

در پایان چه چیزهایی را تحویل بدهی؟Lab handoff: an evidence bundle another engineer can review

چند تصویر صفحه به‌تنهایی کافی نیست. بهتر است کنار هر خروجی یک جملهٔ ساده بنویسی: «این دستور چه چیزی را برای من ثابت کرد؟» اگر نتوانی این جمله را بنویسی، احتمالاً هنوز فقط خروجی جمع کرده‌ای و نتیجه نگرفته‌ای.

If you only have screenshots but cannot support one of these conclusions with command/output evidence, the handoff is incomplete. This may feel slower at first, but in real support work it prevents hours of guessing.

مرجع سریعQuick reference and official sources

docker --version
docker version
docker context show
docker context ls
docker info
docker ps
docker run hello-world

systemctl status docker
systemctl start docker
systemctl stop docker

ls -l /var/run/docker.sock
id

wsl --version
wsl -l -v