Verify Docker Installation

You’ve installed Docker — now what? Running docker run hello-world isn't just a warm fuzzy: it's the mandatory handshake between your machine and the Docker daemon, proving the engine is alive, networking works, and you can pull images. Skipping this step is the #1 cause of "Docker doesn't work" frustration later.

The problem this lesson solves

Imagine you’ve followed an install guide, you see docker --version return something like Docker version 27.0.3, but when you try to build or run a real container — silence or Error response from daemon. The installer finished, but the Docker Engine didn’t start, or your user isn’t in the docker group, or the socket is missing. The hello-world image is the litmus test that catches these silent failures early.

Without this verification, you might waste hours debugging a broken container aqueduct — when the root cause is that the tap was never turned on.

Core concept / mental model

Think of Docker as a three-layer cake: - Client (the docker CLI you type into) - Daemon (dockerd) — the background server that manages containers, images, networks, volumes - Registry (like Docker Hub) — where images live

Running hello-world exercises all three layers: 1. The CLI sends a command to the daemon via /var/run/docker.sock. 2. The daemon checks if the hello-world image is cached locally. 3. If not, it pulls the image from Docker Hub (registry) — validating internet connectivity. 4. It creates a container from that image, runs its default command, prints a test message, and exits.

Pro tip: This is not a “hello world” in the sense of a web page — it’s a sanity check container. The container prints text then stops; no daemonized process runs after.

What “verify Docker installation” actually means

It means confirming: - Docker Engine (daemon) is running. - Your user has permission to access the Docker socket. - The daemon can connect to a registry (unless offline). - The basic image pull + container run cycle works.

How it works step by step

When you run docker run hello-world, here’s the exact sequence:

1. CLI translates docker run hello-world to a REST API call (POST /containers/create?name=hello-world).
2. The daemon receives the request and locates the image hello-world:latest in its local image store.
3. Image not found locally → daemon attempts to pull from Docker Hub (or configured registry mirror).
4. The pull downloads a tarball of filesystem layers ( - Root filesystem: ~5 MB compressed - Small binary that prints the welcome message
5. Daemon creates a container using that image, with default ENTRYPOINT (/hello).
6. The container runs, writes “Hello from Docker!” to stdout, then exits with status 0.
7. The docker run command blocks until the container exits, printing the output to your terminal.

Diagram (in words)

Your terminal
     │
     ▼
docker run hello-world   (CLI)
     │
     ▼  REST API via socket
Docker Daemon (dockerd)
     │
     ├─ Local cache hit? ─ NO ─→ Pull from registry (Docker Hub)
     │
     ▼
Create container from hello-world image
     │
     ▼  Run ENTRYPOINT
Print welcome message → Exit

Hands-on walkthrough

Prerequisites

• Docker installed for your OS
• Terminal access (Command Prompt on Windows, Terminal on macOS/Linux)
• Internet connection (for first pull)

Step 1 — Open your terminal

Open your favorite terminal emulator. On macOS, that’s Terminal.app or iTerm2. On Windows, use PowerShell or Command Prompt (must be run as Administrator if you skipped post-install steps).

Step 2 — Run the command

docker run hello-world

Step 3 — Expected output

You should see something like this (the full message is longer):

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Step 4 — Confirm the container ran and stopped

docker ps -a | grep hello-world

Example output:

CONTAINER ID   IMAGE         COMMAND    CREATED          STATUS                     PORTS     NAMES
d0b5c7a3f8e9   hello-world   "/hello"   2 minutes ago    Exited (0) 2 minutes ago             hopeful_carson

Notice STATUS says Exited (0) — the container ran and finished successfully.

Step 5 — Verify the image was pulled

docker images | grep hello-world

Output:

hello-world   latest    feb5d9fea6a5   3 weeks ago   13.3kB

Now hello-world is cached locally. Any subsequent docker run hello-world will not attempt a pull (unless you delete the image).

Compare options / when to choose what

Recommendation: Always start with hello-world — it’s designed for this purpose. When you need a lightweight image that stays alive (e.g., to exec into), use alpine or busybox.

Troubleshooting & edge cases

“docker: command not found”

• Docker isn’t installed or not in your $PATH.
• Fix: Reinstall Docker. On macOS, ensure the Docker Desktop app is in your /Applications folder. On Linux, check /usr/bin/docker.

“Cannot connect to the Docker daemon”

• The Docker daemon isn’t running.
• Fix:
• macOS: Launch Docker Desktop from the Applications folder (the whale icon in the menu bar).
• Linux: sudo systemctl start docker (or sudo service docker start).
• Windows: Start Docker Desktop from the start menu.

“permission denied while trying to connect to the Docker daemon socket”

• Your user isn’t in the docker group.
• Fix: sudo usermod -aG docker $USER then log out and back in. During setup, you can prefix commands with sudo as workaround.

“No such image: hello-world” / pull fails slowly

• Network issue or Docker Hub is blocked.
• Fix: Run with a registry mirror (e.g., --registry-mirror https://mirror.gcr.io). Or verify that the daemon’s DNS configuration can resolve registry-1.docker.io.

Edge case: Pulling image fails but Docker can still run locally-built images? That’s fine — hello-world validates registry connectivity. If that’s not needed (offline), you can skip this check.

Container runs but prints nothing / very fast exit

• Likely the image was pulled but the container’s ENTRYPOINT didn’t execute. Rare for hello-world, but if you see CONTAINER ID with STATUS Exited (0) and no output, try:

docker logs <container-id>

“The command ‘docker’ could not be found” in Git Bash on Windows

• Docker Desktop is not using WSL 2 integration correctly.
• Fix: Ensure Docker Desktop settings → Resources → WSL Integration → enable for your distribution. Also verify docker is accessible from the WSL terminal.

What you learned & what's next

You now know how to verify Docker installation with hello-world — confirming that your setup is functional end-to-end. You understand the mental model of client ↔ daemon ↔ registry, and you can troubleshoot common installation errors.

In the next lesson, you'll learn how to work with Docker images efficiently — pulling specific versions (nginx:1.25.3), inspecting layers, and cleaning up unused images. You'll build on the foundation of a working Docker environment.

Takeaway: hello-world isn’t just a cute first run; it’s your go-to health check. Whenever something feels broken, run docker run hello-world — it’s the quickest way to spot daemon vs. network vs. permission issues.