The Docker run command

Since we will be using the run command a lot, we should take a look at that now. You have already used the run command in its most basic form:

# new syntax
# Usage: docker container run [OPTIONS] IMAGE [COMMAND] [ARG...]
docker container run hello-world

# old syntax
docker run hello-world

This command tells Docker that you want to run a container based on the image described as hello-world. You may be asking yourself, did the hello-world container image get installed when I installed Docker? The answer is no. The docker run command will look at the local container image cache to see whether there is a container image that matches the description of the requested container. If there is, Docker will run the container from the cached image. If the desired container image is not found in the cache, Docker will reach out to a Docker registry to try to download the container image, storing it in the local cache in the process. Docker will then run the newly-downloaded container from the cache.

A Docker registry is just a centralized location to store and retrieve Docker images. We will talk more about registries and the Docker registry specifically later. For now, just understand that there is a local image cache and a remote image store. You saw the container not found locally process occur when we ran the hello-world container in Chapter 1, Setting up a Docker Development Environment. Here is what it looks like when Docker does not find the container image in the local cache and has to download it from the registry:

You can pre-seed the local docker cache with container images you plan to run by using the docker pull command; for example:

# new syntax
# Usage: docker image pull [OPTIONS] NAME[:TAG|@DIGEST]
docker image pull hello-world

# old syntax
docker pull hello-world

If you prefetch the container image with a pull command, when you execute the docker run command, it will find the image in the local cache and not need to download it again. 

You may have noticed in the preceding screenshot that you requested the hello-world container image and Docker unsuccessfully searched the local cache and then downloaded the hello-world:latest container image from the repository. Each container image description is made up of three parts:

• Docker registry host name
• Slash-separated name
• Tag name

The first part, the registry host name, we have not seen or used yet, but it was included via a default value of the public Docker registry. Whenever you do not specify a registry host name, Docker will invisibly use the public Docker registry. This registry host name is docker.io. The contents of the Docker registry can be browsed at https://hub.docker.com/explore. This is the main public store for Docker images. It is possible to set up and use other public or private image registries, and many corporations will do just that, setting up their own private Docker image registry. We will talk a little more about that in Chapter 8, Docker and Jenkins. For now, just understand that the first part of a Docker image description is the registry host name that hosts the container image. It is worth noting that the registry host name can include a port number. This can be used for registries that are configured to serve data on a non-default port value.

The second part of the container image description is the slash-separated name. This part is like a path to, and name of, the container image. There are certain official container images that do not need to specify the path. For those images, you can simply specify the name portion of the slash-separated name. In our example, that is the hello-world part of the description.

The third part of the container image description is the tag name. This part is considered the version tag for the image, but it does not need to be made up of just numbers. The tag name can be any set of ASCII characters, including uppercase and lowercase letters, numbers, dashes, underscores, or periods. About the only restrictions on tag names are that they cannot start with a period or dash, and have to be 128 characters or fewer. The tag name is separated from the slash-separated name by a colon. This brings us back to the hello-world:latest image description we saw earlier. Like the registry host name, there is a default value for the tag name. That default value is latest. In our example, the tag name being used is the default, and it is shown in the search and download as hello-world:latest. You can see all of this in action in the following example:

We confirmed that our local image cache is empty, with the docker images command, and we then pulled the fully qualified hello-world image to prefetch it into our local cache. Then we used the same short description as we did in all of our previous hello-world examples, and Docker runs the container without downloading again, showing that the default values are used and that they match the fully-qualified values.

Okay, now that we have all of the basics of the Docker run command out of the way, let's dig a little deeper and examine some of the optional parameters that you can use with the run command. If you look at the full run command syntax, you will see this:

# Usage: docker container run [OPTIONS] IMAGE [COMMAND] [ARG...]

Note that the last parts of the command are [COMMAND] [ARG...]. This tells us that the container run command has an optional command parameter that can also include its own optional parameters. Docker container images are built with a default command that is executed when you run a container based on the image. For the hello-world container, the default command is /hello. For a full Ubuntu OS container, the default command is bash. Whenever you run an Ubuntu container and don't specify a command to run in the container, the default command will be used. Don't worry if this doesn't make much sense yet—we will cover the default command and overriding it at runtime later in this chapter in the Back to the Docker run command section. For now, it is enough to know that when you run a container, it will execute a command that is either the default command or, if provided to the container run command, an override command to execute in the running container. One last note: when the command being executed by the running container (either default or override) terminates, the container will exit. In our examples using the hello-world container, as soon as the /hello command terminates inside the container, the hello-world container exits. In a moment, you will learn more about the difference between a running container and one that has exited.

For now, we will continue our run command discussion with one of my favorite optional parameters, the --rm parameter. A little background information is required here. As you may recall from Chapter 1, Setting up a Docker Development Environment, a Docker image is made up of layers. Whenever you run a docker container, it is really just using the locally-cached docker image (which is a stack of layers), and creating a new layer on top that is a read/write layer. All of the execution and changes that occur during the running of a container are stored in its own read/write layer.