Running Your First Docker Container: docker run hello-world

Overview

Now that you have successfully installed Docker on your system (Linux, macOS, or Windows), it’s time to run your very first container! One of the simplest and most fundamental Docker commands is docker run. For comprehensive guidance on the Docker Installation process, kindly refer to this post. In this post, we will guide you through the process of running the hello-world container to verify that Docker is functioning correctly. We will also explain the command in detail so that you understand the underlying processes happening when you run a container.

In this post, we will cover:

1. What is a Docker container?
2. Introduction to the docker run command
3. Running the hello-world container
4. Understanding the output of hello-world
5. Behind the scenes: What happens when you run a Docker container?
6. Troubleshooting common issues when running containers
7. Additional docker run options to explore

1. What Is a Docker Container?

Before we dive into running your first container, let’s briefly revisit what a Docker container is.

A Docker container is a lightweight, standalone, and executable package that contains everything needed to run a piece of software, including the code, runtime, libraries, and system tools. Containers allow developers to create, test, and deploy applications consistently across different environments without worrying about compatibility issues. Containers run as isolated processes on the host operating system, sharing the OS kernel but remaining separate from other processes.

Running containers in Docker is extremely efficient because they’re lightweight compared to traditional virtual machines. You can think of containers as self-contained units that include all the dependencies an application needs to run.

2. Introduction to the docker run Command

The docker run command is the fundamental command used to run containers in Docker. It allows you to pull images from Docker Hub (the central repository for container images), create a container from that image, and run the container as a process on your host machine.

The basic syntax of the docker run command is as follows:

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Where:

• IMAGE: The name of the Docker image you want to run. If the image is not available locally, Docker will pull it from Docker Hub automatically.
• COMMAND: (Optional) The command you want to run inside the container. If not specified, Docker will execute the default command for the image.
• OPTIONS: (Optional) Various options that modify the behavior of the container, such as port mapping, environment variables, or interactive mode.

3. Running the hello-world Container

The hello-world container is the perfect starting point for learning how to run Docker containers. It is a small and simple container that, when executed, prints a message confirming that your Docker installation is working.

Step 1: Open a Terminal

To run Docker commands, you need to open a terminal (on Linux or macOS) or a Command Prompt/PowerShell window (on Windows).

Step 2: Run the hello-world Container

Execute the following command to run the hello-world container:

docker run hello-world

This command does the following:

1. Pulls the hello-world image from Docker Hub if it’s not already present on your local machine.
2. Creates a new container based on the hello-world image.
3. Runs the container, which in turn runs the default command inside the image.
4. The container prints a message to the terminal and then exits.

Step 3: Verify the Output

If everything is working correctly, you should see output similar to the following:

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.

4. Understanding the Output of hello-world

Let’s break down the output to understand what is happening:

• Docker client contacted the Docker daemon: When you run docker run, you are using the Docker CLI (client) to communicate with the Docker daemon (the background process that manages containers). The client sends a request to the daemon to perform the requested operation.
• Docker daemon pulled the image from Docker Hub: If the hello-world image was not already present on your local system, Docker automatically pulled it from Docker Hub, the default image registry. This happens behind the scenes without any additional configuration.
• Docker daemon created a new container: Once the image is pulled, Docker creates a new container based on that image. A container is a runtime instance of the image, and it behaves like an isolated process running on your system.
• Docker daemon streamed the output to the client: The hello-world container runs a small program that prints the "Hello from Docker!" message. This output is captured by the Docker client and sent back to your terminal.

After running the container and displaying the message, the container exits. In this case, the container doesn’t keep running because the command inside the container has finished executing.

5. Behind the Scenes: What Happens When You Run a Docker Container?

Running docker run triggers several processes behind the scenes. Here’s a detailed breakdown:

1. Docker Client Interaction: When you run the docker run command, the Docker client communicates with the Docker daemon, instructing it to start a new container. One of Docker's powerful features is its client-server architecture, allowing the Docker client to communicate with a remote Docker daemon, meaning they don't have to run on the same host.
2. Image Check: Docker checks whether the specified image (in this case, hello-world) is available locally. If it is not, Docker will pull it from Docker Hub. Docker users aren't limited to Docker Hub; they can configure and pull images from multiple registries, offering flexibility for custom or private repositories.
3. Container Creation: When you run a Docker container, Docker uses a layered approach to build and execute it. The process begins with the Docker client sending a request to the Docker daemon, which checks for the specified image in its local cache. If the image isn’t available locally, Docker pulls it from a registry, typically Docker Hub or a specified registry. The image itself is composed of layers, where each layer represents a set of file changes or additions, stacked together to form the final image. Docker then initializes a container from this image by setting up namespaces and control groups, isolating the container’s process and resources from the host system. With the container environment now ready, Docker executes the specified command, effectively bringing the container to life.
4. Command Execution: The container runs the command specified by the image (or a custom command provided by the user). In the hello-world image, there’s an embedded command set as the entrypoint (an executable script or binary) that Docker runs when the container starts. In this case, the hello-world image has a simple entrypoint that prints a friendly message to the terminal. Docker creates a process within the container’s isolated environment and executes the command to print the text.
5. Container Lifecycle: Once the command finishes running, the hello-world container stops since there are no additional commands to keep it running. By default, Docker containers stop when the main process inside the container completes. You’ll see the output message from the container in your terminal, indicating that the container successfully executed its task and exited.

6. Troubleshooting Common Issues When Running Containers

Issue 1: Docker Daemon Not Running

If you see an error message like Cannot connect to the Docker daemon, it means that the Docker service (daemon) is not running. To fix this, you need to start the Docker daemon:

• On macOS/Windows: Open Docker Desktop and make sure it’s running.

On Linux:

sudo systemctl start docker

Issue 2: Network Connectivity Issues

If Docker is unable to pull the hello-world image from Docker Hub, check your internet connection and ensure that your system can reach Docker Hub. You can verify connectivity by running:

ping hub.docker.com

If there are proxy settings or firewall configurations in place, they may need to be adjusted.

Issue 3: Permission Issues (Linux)

If you receive a permission denied error when running Docker commands, you might not have the necessary permissions to use Docker without sudo. To fix this, add your user to the docker group:

sudo usermod -aG docker $USER

Then, log out and log back in for the changes to take effect.

7. Additional docker run Options to Explore

The docker run command has many options that allow you to customize the behavior of containers. Some commonly used options include:

Volume Mounting (-v): Mount a directory from the host into the container, enabling data persistence:

docker run -v /host/path:/container/path nginx

Detached Mode (-d): Run a container in the background (detached), allowing you to continue using the terminal:

docker run -d redis

Port Mapping (-p): Map ports between the host and container, which is useful when running web applications inside containers:

docker run -p 8080:80 nginx

Interactive Mode (-it): Run a container interactively with a terminal session, which is useful for testing or debugging:

docker run -it ubuntu /bin/bash

These are just a few of the many options available. As you continue working with Docker, you’ll find that docker run is one of the most versatile commands in your Docker toolbox.

Conclusion

Running your first container with docker run hello-world is the first step in your Docker journey. It’s a simple, lightweight way to verify that your Docker installation is working correctly. Along the way, you’ve learned about how Docker containers work, what happens behind the scenes when you run a container, and how to troubleshoot common issues.