What Just Happened? Tracing the docker run Command
LEVEL 0
The Problem
You typed six words: docker run hello-world. A lot happened. But what exactly?
Understanding the docker run command deeply is crucial. It’s the command you’ll use most, and its behavior has many nuances we’ll uncover throughout this curriculum.
LEVEL 1
The Concept — The Order Form
The Concept
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)
LEVEL 2
The Mechanics — Breaking Down the Command
The Mechanics
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 namelatest— the default tag
So docker run hello-world and docker run docker.io/library/hello-world:latest are equivalent.
LEVEL 3
The Full Process
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!)
LEVEL 4
Container States
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