Docker's run command is, by far, the most frequently used command in Docker world. Briefly, the run command performs the following two operations:

1. downloads an image from an online registry, which by default, is Docker Hub.

2. runs the downloaded image to spin up an instance of a container.

This is illustrated below:

In its most basic form, the run command looks like the following:


        
        
            
                
                
                    $ docker run <image_name>

For instance, we can obtain and run an image called hello-world using the following command:


        
        
            
                
                
                    $ docker run hello-world
                
            
            Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
7050e35b49f5: Pull complete 
Digest: sha256:aa0cc8055b82dc2509bed2e19b275c8f463506616377219d9642221ab53cf9fe
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows that your installation appears to be working correctly.

Here, since we don't have a local copy of the image in our machine, we fetched (or pulled) the image from Docker Hub. Using this downloaded image, Docker created a new container and executed the associated program within this container. As you can see from the output, the program simply prints "Hello from Docker!". Once the program finishes, the container is terminated and memory/computing resources are handed back to the host machine.

To see a list of images on your local machine, run the following command:


        
        
            
                
                
                    $ docker images
                
            
            REPOSITORY      TAG       IMAGE ID       CREATED         SIZE
hello-world     latest    46331d942d63   11 months ago   9.14kB

As you can see, the hello-world image has indeed been downloaded on your local machine! Let's now clarify two confusing points about the output - the REPOSITORY field and the CREATED field.

Let's go over the CREATED field first. In the output, the CREATED date for our image is "11 months ago", which is confusing because we've just downloaded this image a few moments ago. The CREATED date is actually the date in which the image was created by the original creator of the image.

The REPOSITORY is defined as a collection of images. For instance, suppose we pulled the official python image:


        
        
            
                
                
                    $ docker pull python

Docker will automatically pull the latest version of the image, which at the time of this writing is version 3.9. Now, let's pull another python image of version 3.7 like so:


        
        
            
                
                
                    $ docker pull python:3.7

The latest version of python and specific version 3.7 of python belongs to the same repository, but they are two separate images. This is confirmed when we run the following command:


        
        
            
                
                
                    $ docker images
                
            
            REPOSITORY            TAG       IMAGE ID       CREATED         SIZE
python                3.7       b0dc71b2bb25   4 days ago      857MB
python                latest    215d55a69ad3   4 days ago      875MB

Flags

In this section, we will go over some useful flags that we can specify for the run command.

Detached mode (-d)

The -d flag allows us to run the container in the background. Without the -d flag, the container would run in the foreground and prevent us from using the command line. To demonstrate this, let's run the following command:


        
        
            
                
                
                    $ docker run nginx

If you've never heard of nginx before, just think of it as a web server. Notice how no output is shown on the command line since the nginx server has taken over the main process of the command line. This also means that anything that your server prints will appear on the command line. Press ctrl + c to hand back the foreground process to the command line.

Let's now run same command, but this time with the -d flag:


        
        
            
                
                
                    $ docker run -d nginx
                
            
            bd9f624bdfd5844f7cbe7d6ac5f12537285091237208bf076169ad3f01645d00

The long text that is returned is the id of the container that was built. The server is now running in the background and you still have control over the command line!

Naming containers (--name)

The --name flag allows you to name the container that is built. Take note of the the double hyphens (--); only having one would throw an error.

Let's go through a quick example. Suppose we ran the following command:


        
        
            
                
                
                    $ docker run --name skytowner -d nginx
                
            
            7432e36f5433295a647a3305db921948f5b6660fd643fc07b072d36882e41f3b

Here, we are using the detach mode to deploy a nginx server, with the container name as skytowner. We can use the ps command to check that the name of the container is indeed what we specified:


        
        
            
                
                
                    $ docker ps -a
                
            
            CONTAINER ID  IMAGE  COMMAND                 CREATED        STATUS        PORTS   NAMES
7432e36f5433  nginx  "nginx -g 'daemon of…"  7 minutes ago  Up 7 minutes  80/tcp  skytowner

Note that, if we do not specify the name for our container, Docker will automatically create one for us.

Binding ports (-p)

Without it, there is no way for programs outside the container to connect to the programs running within it. Remember, even though containers reside in the host machine, they are still isolated from the host machine. In other words, the host machine and the container cannot interact with each other by default. This is a problem for cases when we want to connect and interact with the program running inside the container.

To allow interaction between the container and the host machine, we can use so-called ports, which are numbers that behave like addresses. We can assign a port, say 5000, to the container and bind that with another port in the host machine, say 8080. This is illustrated below:

As a concrete example, suppose the container represents a nginx web server and our program represents a web application. By using ports, our web application will be able to send and retrieve data from our nginx web server.

To set this up, we can use the -p flag when running the image. The parameter we provide for the -p flag is host_ip:host_port:container_port. The host_ip is optional, and defaults to 0.0.0.0 (http://localhost:8080).

Let's go through an example. Suppose we ran the following command:


        
        
            
                
                
                    $ docker run -p 8080:5000 -d nginx
                
            
            721521daaa90a0fc770f65a3b01035fad5031dc6038896c36327d97059ae92b1

To check the mapping of the ports, use the ps command:


        
        
            
                
                
                    $ docker ps
                
            
            CONTAINER ID  IMAGE  PORTS
721521daaa90  nginx  80/tcp, 0.0.0.0:8080->5000/tcp

Note that some columns were omitted for brevity. The 8080->5000 means that anyone who connects to the port 8080 of the local host (machine), will be redirected to port 5000 of the container, which is the location of the running container.

Now that we've confirmed our nginx server is running, let's actually interact with it by opening up your browser and heading to localhost:8080. You should see the following:

The -p flag can be specified multiple times in the same command, so we can have multiple mapping between the ports of the local machine and those of the container.

Published by Isshin Inada

Edited by 0 others

Did you find this page useful?

thumb_up

thumb_down

Comment

Citation

Ask a question or leave a feedback...

thumb_up

thumb_down

chat_bubble_outline

settings

Enjoy our search

Hit / to insta-search docs and recipes!