What Just Happened? Tracing the docker run Command

Think of docker run as placing an order at a restaurant.

“I’d like the hello-world, please.” (docker run hello-world)

The kitchen (Docker daemon) receives your order. They check if they have the ingredients (image). If not, they send someone to the store (registry). Once they have everything, they prepare the dish (create container) and serve it (run container).

But unlike a restaurant where you wait at your table, with Docker you can choose:

• Wait and watch: See the output as it happens (foreground)
• Order and leave: Come back later for the result (background/detached)

docker run hello-world

Let’s dissect this:

docker: The CLI program. This is what you’re executing.

run: The command. “Run a container.” This is actually shorthand for: create a container AND start it.

hello-world: The image name. More specifically, this expands to docker.io/library/hello-world:latest:

• docker.io — the default registry (Docker Hub)
• library — the default namespace (official images)
• hello-world — the repository name
• latest — the default tag

So docker run hello-world and docker run docker.io/library/hello-world:latest are equivalent.

Here’s the complete sequence with more detail:

1. CLI parses the command The Docker CLI validates the command syntax and prepares an API request.

2. CLI connects to daemon On Linux: via Unix socket at /var/run/docker.sock On Mac/Windows: via a socket connection to the Docker Desktop VM

3. Daemon receives “create and start container” request The daemon extracts the image reference: hello-world:latest

4. Daemon resolves the image

• Check local store: do we have hello-world:latest?
• If yes, use the local copy
• If no, pull from the registry

5. (If needed) Pull from registry

• Connect to Docker Hub
• Authenticate (for private images)
• Download image layers
• Store in local image cache

6. Create container

• Allocate a unique container ID
• Create a writable layer on top of the image
• Set up namespaces (PID, network, mount, etc.)
• Configure cgroups for resource limits
• Prepare the root filesystem

7. Start container

• Execute the container’s startup command (for hello-world: a small binary)
• The process runs inside the isolated environment
• stdout/stderr are captured

8. Stream output

• The daemon streams output back to the CLI
• The CLI prints it to your terminal

9. Container exits

• The process completes
• Exit code is recorded
• Container enters “stopped” state (but still exists!)

After running, check:

docker ps

Nothing shows up. Why? docker ps shows running containers. The hello-world container ran and exited.

Try:

docker ps -a

Now you see it — in “Exited” status. The container still exists; it’s just not running.

This is important: containers persist after they stop. They consume disk space. They can be restarted. They hold logs and the final state of their filesystem.

To clean up:

docker rm <container_id>

Or, to remove all stopped containers:

docker container prune

---