"Whoami" is the name of a simple image that is great for learning Docker. If you're wondering what an image is, that will be explained below.

Whoami is like the โ€œHello world!โ€ of Docker. It is a minimal, but realistic example of a service someone might run with Docker. We'll use it in this section to show the basic stages of the lifecycle of a container, which will be exactly the same principles involved in running any application - including our Coti node.

On a high level, the steps covered in this page are:

Running a Container

First, I'll introduce the command to use, show you the output, and then explain what just happened. To run a whoami container, use

docker run -p 80:80 containous/whoami

What does this mean?

  • docker refers to Docker's command

  • run tells the docker cli that you want to run a container

  • -p 80:80 tells Docker to map port 80 from the outside of the container, to port 80 on the inside of the container. Ports are closed by default on containers (this is a security feature), which is why we need to tell it which port to open.

  • containous/whoami refers to the "whoami" Docker image. You can find it on Dockerhub. "containous" is the organization that created the image, and "whoami" is the name of the image. Dockerhub is an example of an image registry. You can think of an image registry as like a library for container images. Dockerhub is not the only image registry, although it is generally the most popular one.

When I ran the command above, this was the output:

Unable to find image 'containous/whoami:latest' locally
latest: Pulling from containous/whoami
29015087d73b: Pull complete 
0109a00d13bc: Pull complete 
d3caffff64d8: Pull complete 
Digest: sha256:7d6a3c8f91470a23ef380320609ee6e69ac68d20bc804f3a1c6065fb56cfa34e
Status: Downloaded newer image for containous/whoami:latest
Starting up on port 80

Here's a breakdown, line by line, of what happened:

  • Line 1: Docker checked the local cache for the image, and informs us that it couldn't find the image.

  • Line 2: Since Docker couldn't find the image locally, it goes to Dockerhub and pulls (downloads) the image.

  • Lines 3-5: Docker images are made in layers, so each line corresponds to one layer pulled by Docker.

  • Line 6: This shows a checksum of the download. Checksums are a security feature that allows you to check whether downloaded files have been tampered with.

  • Line 7: This is a status report that tells us that the download is complete.

  • Line 8: This is a log from the "whoami" application itself, telling us that it has started, and it is running on port 80.

A lot happened there. The important parts are that Docker downloaded the image we requested, and ran it. It is possible to download and run the image in separate steps, but Docker typically isn't used that way.

Once the image is downloaded, it is saved on the computer, so that it doesn't need to be re-downloaded every time we run the application. The command above will work regardless of whether the image has already been downloaded or not.

Checking a Container is Up

In the last line of the output above, Docker says something is running on port 80? Let's test that out. In a new terminal tab/window, run

curl http://localhost:80

The output I received was:

Hostname: a61ec392609e
GET / HTTP/1.1
Host: localhost
User-Agent: curl/7.79.1
Accept: */*

If you received similar output, congratulations! That is a successful response from whoami, and you successfully got a response from your first Docker container ๐ŸŽ‰

The Hostname is the ID of the container that we created. The other information mostly reflects back the HTTP headers that were sent by curl.

I suggest you also try visiting http://localhost:80 in a browser, and you will get back even more information (since the browser sends more headers).

That's pretty cool. We launched an application with just one command, and without writing any code.

Checking Running Containers with Docker

We can also check whether a container is running with the Docker cli. To do this, use

docker ps

You can think of docker ps as like the ls command, in that it lists the running containers.

The output I received was

CONTAINER ID   IMAGE               COMMAND     CREATED          STATUS          PORTS                NAMES
a61ec392609e   containous/whoami   "/whoami"   16 seconds ago   Up 15 seconds>80/tcp   pensive_dubinsky

Notice the container ID matches the Hostname presented to us by Whoami. The command also gives some basic information about the running container (e.g. the port mapping, how long the container has been running).

Stopping a Container

Ending a container's lifecycle is just as important as starting it. Without stopping our containers, we would eventually have huge numbers of containers using up our resources.

There are two ways to stop Docker containers. Since we ran whoami interactively, we can stop the container simply by entering Ctrl+c (cancel) in our terminal.

A good way of checking that the container has stopped, is by running docker ps. The output no longer shows our whoami container.

docker ps

You can also check that the container has stopped by visiting http://localhost:80 again.

Although the container is stopped, that does not mean it has been fully deleted. A -a option (short for "all") can be added to the docker ps command to ask Docker to show all containers. So, to see our stopped container, use

docker ps -a

which shows an output of

CONTAINER ID   IMAGE                            COMMAND                  CREATED          STATUS                          PORTS     NAMES
a61ec392609e   containous/whoami                "/whoami"                2 minutes ago   Exited (2) 1 minute ago                 pensive_dubinsky

Removing a Container

In most cases, stopping a container is enough, but to understand all the steps, we'll demonstrate removing a container too.

Copy the CONTAINER ID from the previous step. Then to remove the container, we run

docker rm <CONTAINER_ID>

When it is successful, docker rm returns the ID of the removed container. If you ever want to remove more than one container at once, you can simply add many container IDs, separated by spaces.

Running docker ps -a again shows that the container has been removed! Great.

docker ps -a
CONTAINER ID   IMAGE                            COMMAND                  CREATED          STATUS                         PORTS     NAMES


Although the application we ran, whoami, was very simple, we introduced some key concepts that are part of any application's lifecycle, namely:

  • Running a container

  • Checking it is up

  • Stopping a container

  • Removing a container

These are the most important concepts to understand when using Docker. If you managed to follow these steps, you are about 80% of the way to becoming a fully fledged Docker user! Awesome.

Last updated