How to Use the docker run Command

Introduction

Before we begin talking about how to use the docker run command, let's briefly understand – What is docker run command?

The docker run command is a fundamental command in Docker that allows you to create and run a new container based on a specific Docker image. It combines the steps of creating a container from an image, starting the container, and running a command within the container.

With the docker run command, you can specify various options and configurations to customize the container's behavior, such as networking, port mapping, volume mounting, environment variables, resource allocation, and more. It provides a simple and convenient way to start and manage Docker containers.

In this tutorial, you will use the docker run command. We will also address a few FAQs on how to use the docker run command.

Prerequisites

Access to a terminal window or command line.
A user account with sudo privileges.
A successfully installed Docker

💡

Note: You can execute these commands either as the root user or as a user with sudo privileges, in which case you must add the sudo prefix.

How to Use the docker run Command

The general syntax for the command is:

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

The only thing you must specify in the command line to run a container is the image on which it is based:

docker run [docker_image]

Docker images that are locally stored can be used to run containers. When you use an image that is not already on your machine, the software retrieves it from the online registry.

A sample Docker image with the task to echo the phrase Hello World was created using a Dockerfile as an example. The image has the ID e98b6ec72f51 for us. Depending on the container you intend to use, your image name will change.

To run our test container, issue the following command:

docker run e98b6ec72f51

After completing the required task (repeating the phrase Hello World), the container terminates.

💡

Note: With the introduction of Docker 1.13, a new CLI has been unveiled that reorganized commands into groups based on the objects they interact with. In light of this, run is now a subcommand of docker container, and you must type docker container run to use it. Docker still supports docker run, however, it advises becoming familiar with the new syntax.

Run a Container Under a Specific Name

Docker creates a container name using a string of randomly chosen digits and letters when you execute the basic run command.

Consider changing the container name to something more memorable because there is a very small probability that you will be able to recall or recognize the containers by their generic names.

You can give a container name by using the --name attribute. Running a container with a particular name requires the following command:

docker container run --name [container_name] [docker_image]

For example, we can run the sample container and assign it the name container_instance using the command:

docker container run --name container_instance e98b6ec72f51

With the command below, you may check to see if you have set a container name correctly by displaying a list of all containers (both running and stopped):

docker ps -a

You should see your newly created container, as shown in the image below.

Run a Container in the Background (Detached Mode)

Running a container can be done in two different ways: attached mode (foreground) or detached mode (in the background).

Docker runs the container in the attached mode by default. That is, it is attached to the terminal session, where it shows output and messages.

You can use the -d attribute to run the container in the background if you wish to keep the current terminal session and container separate. You can close the active terminal session while still running the container by using detached mode.

For running a container in the background, use the following command:

docker container run -d [docker_image]

The command we're using for our example is :

docker container run -d e98b6ec72f51

The output you get will resemble the one in the image above. The process will be run by the container and then terminated. The terminal session will not display any additional output.

💡

Note: One of the most used run commands is running Docker privileged containers. However, did you realize that using privileged containers is not recommended owing to a possible threat to the system?

Run a Container Interactively

You may run a container in interactive mode thanks to Docker. This indicates that while the container is still running, commands can be run inside of it.

You can access a command prompt inside the running container by using the container interactively. Use the following command to do that:

docker container run -it [docker_image] /bin/bash

The command prompt will alter, transferring you to the bash shell, as in the example below.

Run a Container and Publish Container Ports

The only way to access a process when running a container is from within it. The container must have certain ports opened (published) in order to accept connections from outside sources.

The following information must be added to the docker run command along with the -p option:

-p [host_ip]:[host_port]:[container_port]

You do not have to specify the host_ip element when running the command; it is optional.

For instance, you might run the following command to map TCP port 80 from the container to port 8080 on the Docker host:

docker container run -p 8080:80 [docker_image]

Run a Container and Mount Host Volumes

The data that Docker containers generate is not saved. The container stops when the procedure is complete, and everything within is removed.

If you want persistent data that will be stored even after the container stops, you need to activate sharing storage volumes.

Use the -v attribute with the directory location you wish to save the data in, followed by the location of the data inside the container, when mounting volumes.

-v [/host/volume/location]:[/container/storage]

This is the complete docker container run command:

docker container run -v [/host/volume/location]:[/container/storage] [docker_image]

Run a Docker Container and Remove it Once the Process is Complete

As a container completes its tasks, it exits, but the file system it is made up of remains on the system.

If you only require a container to carry out the specified task and will not need it or its file system again, you can configure it to delete after it is done.

Use the following command to run a container that will be automatically deleted after it exits:

docker container run --rm [docker_image]

💡

Note: Want to eliminate any additional pointless containers from the system? For further information, see How to Remove Docker Containers, Images, Networks, and Volumes.

FAQs to Use the docker run Command

How can I specify a custom container name when running with `docker run`?

You can use the --name flag followed by your desired name, e.g., docker run --name my_container image_name.

How do I attach a container to a specific network with `docker run`?

To attach a container to a network, you can use the --network flag followed by the network name, e.g., docker run --network my_network image_name.

How can I expose specific ports when running a container with `docker run`?

You can use the -p flag followed by <host_port>:<container_port> to map specific ports, e.g., docker run -p 8080:80 image_name.

How do I mount a volume with `docker run`?

To mount a volume, you can use the -v flag followed by <host_path>:<container_path>, e.g., docker run -v /host/path:/container/path image_name.

Can I run a container in detached mode with `docker run`?

Yes, you can use the -d flag to run the container in detached mode, e.g., docker run -d image_name.

How can I set environment variables with `docker run`?

You can use the -e flag followed by key=value to set environment variables, e.g., docker run -e MY_VAR=my_value image_name.

How do I remove a container after it finishes running with `docker run`?

You can use the --rm flag to automatically remove the container after it stops, e.g., docker run --rm image_name.

Conclusion

In terms of development trends, Docker has established itself. It is best if you become familiar with its command line interface as soon as possible. The first step is to use the docker run command.

If you have any suggestions or queries, kindly leave them in the comments section.