Docker run Command

Introduction to Docker run Command

The ‘docker run’ command is used to run or start a command in a new container which means it creates a writeable layer on top of the mentioned image in the command. That’s why we call a container is a writeable image. This is the first command that we run when start learning Docker. There are a lot of options available with this command to configure the container as per our requirement like running a container in detached mode or interactive mode, specifying a name to the container, attaching network, volume, etc., exposing port to access the containers’ application externally, and many more things.

Syntax

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

Options:

-d, –detach: It is used to run the container in the background and print container ID.

-e, –env: It is used to set environment variables in the container.

-h, –hostname: It is used to change the hostname of the container.

-i, –interactive: It is used to interact with the container

–isolation: It is used to specify container isolation technology

-l, –lable: It is used to add metadata to the container.

–link: It adds a link to another container

–log-driver: It is used to specify the logging driver for the container, it overrides the default log-driver

–log-opts: It is used to specify options to log-driver.

-m, –memory: It is used to set memory limit in bytes

–mount: It is used to mount filesystem to the container

–name: It is used to specify the name of the container

–network: It is used to connect the container to a different network than the default

-p, –publish: It is used to publish container’s ports to host

–restart: It allows us to specify restart policy for the container

–rm: It removes the container as soon as container exit or stop running

-t, –tty: It allocates terminal and mostly used with the ‘-i’ option.

-v, –volume: It is used to bind volume to the container for persistent storage

-w, –workdir: It allows to set the working directory of the container

The above options are the most common that we frequently use while working with the ‘docker run’ command. We can use the ‘–help’ option to list all available options of this command as below: –

docker run --help

How run Command Works in Docker?

When we run the ‘docker run’ command on the terminal, Docker daemon searches for the mentioned Docker image locally and if it finds the image locally then it creates a writeable layer over the specified Docker image and starts the container using specified command and if it does not find the image locally then it firsts pull that image from the registry and by default, it goes to ‘hub.docker.com’ if there is no local registry mentioned in the daemon.json file.

Examples of Docker run Command

Here are the following examples mention below

Example #1

Let’s run our first container ‘hello world without specifying any options as shown below:

docker run hello-world

Explanation: In the above snapshot, we can see that the ‘hello-world’ image was not available locally so daemon first pulled that image locally and ran the container and the ‘hello-world’ container has shown some data on STDOUT and exited.

Example #2

Let’s give a name to the container using the ‘–name’ option as below:

docker run –name nginx-con nginx

Explanation: In the above example, created an nginx container named ‘nginx-con’. If we don’t use the ‘–name’ option then the daemon randomly picks any name and assigned to the container. Also, we can see that the cursor is stuck and we did not get the terminal because the container is running in the foreground. We use ‘ctrl+c’ to exit the container, however, it stops the container as well.

Example #3

Let’s run the container in detached mode to overcome the above issue using the ‘-d’ option as shown below:

docker run -d --name nginx-con2 nginx

 

Explanation: In the above example, we only got the container ID because the container is now running in the background and also this time daemon did not pull the image because nginx image is already available locally.

Example #4

Now, set environment variables using the ‘-e’ option as below:

docker run -d -e "USER=test1" --name nginx-con nginx

Explanation: In the above example, we have used the ‘-e’ option to set an environment variable USER to test1. Now, if we want to verify that the USER environment variable created inside the container or not, we can connect to the container using the ‘exec’ command with ‘-i’ and ‘-t’ options together as shown below: –

docker exec -it nginx-con sh
#echo $USER

 

Explanation: In the above snapshot, we have connected to the container with its name, however, we can use container ID as well and the container must be in running state in order to connect to it.

Example #5

We can also use the above options with the ‘docker run’ command as shown below:

docker run -it -e "USER=test1" --name nginx-con nginx sh

Explanation: In the above example, we can see that we have not used the ‘-d’ option otherwise it will run the container in the background and will not able to connect to the container which means we cannot use the ‘-d’ and ‘-it’ options together.

Example #6

Let’s assume we have to create an nginx container named ‘my-nginx’ with the below configuration:

• Attach a volume named my-vol
• Attach a network named my-net
• Restrict memory utilization to 256 MB
• Open port 80 to access nginx externally
• Set restart policy to unless-stopped
• Set the hostname of the container to ‘my-nginx’

Here is the ‘docker run’ command to achieve the above objective: –

$ docker run -it -v my-vol:/root --network=my-net -m 256m -p 80:80 --restart=unless-stopped -h my-nginx --name my-nginx nginx sh

Explanation: In the above example, we have used the ‘-it’ option to connect to the container directly to verify the hostname otherwise we can use the ‘-d’ option. Note: – Network must exist before creating the container. We can create a simple network using the below command:

docker network create my-net

Example #7

Sometimes we create a container for testing purposes and the container is no longer required after testing so we can use the ‘–rm’ option to delete the container once it is stopped. Here is the command:

docker run --it --rm ubuntu sh

Explanation: In the above snapshot, we can see that there is no container running before and after the creation of the ‘ubuntu’ container because once we exit from the container, it is removed. We can use it for testing the connection between two containers using the ping command directly in the command line.

Advantages

1. The ‘docker run’ is a short command to run a container as compared to the ‘docker container run’ command.
2. It has a lot of options to configure the containers as per our requirements.

Rules and Regulations for using a run Command

1. Docker network must exist before attaching to any container using the ‘docker run’ command.
2. Docker volume gets created if it does not exist already when attaching to any container.
3. There is pointless to use the ‘-d’ and ‘-it’ options together.
4. We can use the same port for the different container but not at the host level, for example, we can create multiple nginx containers and open port 80 on each container but we can not expose these containers externally on the same port, we need to expose each container on a different port to access it externally.
5. Some options only work with a specific version of Docker so it is recommended to check the compatibility before using that option.

Conclusion

The ‘docker run’ command has a lot of options but not all the options are used frequently so we have only discussed the most frequently used options. You can read official documentation to know all the options or use the ‘–help’ option to get all available options.

Recommended Articles

This is a guide to Docker run Command. Here we discuss How to run Command Works in Docker along with multiple Examples with their explanation. You may also have a look at the following articles to learn more –

1. Advantages of Docker
2. Docker Swarm Architecture
3. Install Docker
4. What is Docker in Linux?