Running Hello World: Your First Docker Container Lifecycle

Previously in this course, we explored the virtual machines vs containers architectural shift and completed the setting up the Docker engine process. Now that your environment is ready, it is time to execute your first container.

In this lesson, we will use the canonical hello-world image to demystify the docker run command and observe how a container moves from a static image to an active process.

The docker run Command from First Principles

The docker run command is the primary entry point for interacting with the Docker daemon. When you invoke it, you are instructing the Docker engine to perform a sequence of operations that turn a static "blueprint"—the container image—into a running instance.

The command follows a specific sequence:

1. Locate: Check if the requested image exists locally.
2. Pull: If the image is missing, fetch it from a remote registry (like Docker Hub).
3. Create: Allocate a writable layer on top of the image to prepare the container environment.
4. Execute: Start the process defined in the image's metadata.

Worked Example: Executing Hello World

Open your terminal and run the following command:

Bash
docker run hello-world

If this is your first time running this, you will see output indicating that Docker is pulling the image from the registry. Once the download completes, you will see a message printed to your terminal:

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

Understanding the Container Lifecycle

It is a common misconception that a container must stay "running" indefinitely. In reality, a container is simply a process. Once the main process inside the container finishes its execution, the container exits.

We can visualize this lifecycle with a simple state transition:

Flow diagram: Image → docker run; docker run → Process Running; Process Running → Task Complete; Task Complete → Stopped Container

In the hello-world example:

1. The container started.
2. It executed a script that printed the "Hello from Docker!" text to standard output (stdout).
3. The script finished.
4. The container transitioned to a stopped state.

Hands-on Exercise: Observing the Lifecycle

To reinforce your understanding of the container lifecycle, let's verify that the container is indeed stopped rather than deleted.

1. Run docker ps. You will notice the list is empty. This command only shows running containers.
2. Now, run docker ps -a. You will see your hello-world container listed with a status like Exited (0).

Your Task: Identify the "Container ID" from the output of docker ps -a for your hello-world run. Note that even though the container is stopped, it still occupies space on your disk until you explicitly remove it. We will cover how to clean these up in the next lesson.

Common Pitfalls

• Assuming Containers are VMs: Beginners often expect to "log in" to a container immediately. Remember, if the container's process is just a one-off script, the container stops as soon as the script finishes.
• Ignoring Registry Connectivity: If your machine cannot reach the internet, docker run will fail during the "Pull" phase. Always ensure your Docker engine has network access to pull public images.
• Confusing Images and Containers: Think of the Image as the recipe (the file on disk) and the Container as the meal (the running instance). You can have many containers (meals) created from a single image (recipe).

FAQ

Why did my container stop immediately? Containers only run as long as their primary process is active. The hello-world container is designed to print a message and exit. If you want a container to stay running, you must provide a process that does not exit, such as a web server or an infinite loop.

Does docker run download the image every time? No. Once an image is pulled to your local machine, docker run will use the local copy. You can see your local images by running docker images.

What if I get a "permission denied" error? This usually means your user is not in the docker group. Refer back to the installation guide to ensure your user has the correct permissions to communicate with the Docker daemon.

Recap

In this lesson, we moved from theory to practice. You learned that docker run is the command that initiates the container lifecycle, transitioning an image into a process. You observed that containers exit when their internal task completes, and you verified this state using the docker ps -a command.

Up next, we will dive into Managing Container States, where you'll learn how to start, stop, and interact with containers that don't just exit immediately.