How to Use Docker Run Command with Examples

Introduction

One of the first and most important commands Docker users learn is the docker run command. This comes as no surprise since its primary function is to build and run containers.

There are many different ways to run a container. By adding attributes to the basic syntax, you can configure a container to run in detached mode, set a container name, mount a volume, and perform many more tasks.

In this tutorial, you will learn how to use docker run commands with examples. 

Prerequisites

• Access to a command line/terminal window
• A user account with sudo privileges
• An existing Docker installation

How to Use the docker run Command

The basic syntax for the command is:

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

To run a container, the only thing you need to include in the command is the image on which it is based:

docker run [docker_image]

You can run containers from locally stored Docker images. If you use an image that is not on your system, the software pulls it from the online registry.

As an example, we used a Dockerfile to create a sample Docker image with the task to echo the message Hello World. For us, the image has the ID e98b6ec72f51. Your image name will differ depending on the container you want to run.

The command to run our sample container would be:

docker run e98b6ec72f51

The container performs the prescribed task (echoes the message Hello World) and then stops.

Run a Container Under a Specific Name

When you use the basic run command, Docker automatically generates a container name with a string of randomly selected numbers and letters.

Since there is a slim chance you will be able to remember or recognize the containers by these generic names, consider setting the container name to something more memorable.

Using the --name attribute allows you to assign a container name. The command for running a container under a specific name is:

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

For instance, we can run the sample container and give it the name container_instance using the command:

docker container run --name container_instance e98b6ec72f51

You can check whether you have successfully set a container name by displaying a list of all containers (running and stopped) with the command:

docker ps -a

As in the image below, you should see your newly created container.

Run a Container in the Background (Detached Mode)

There are two ways of running a container – in attached mode (in the foreground) or in detached mode (in the background).

By default, Docker runs the container in attached mode. Meaning it’s attached to the terminal session, where it displays output and messages.

If you want to keep the container and current terminal session separate, you can run the container in the background using the -d attribute. Using detached mode also allows you to close the opened terminal session without stopping the container.

The command for running a container in the background is:

docker container run -d [docker_image]

For our example, the command is:

docker container run -d e98b6ec72f51

The output you receive will be similar to the one you see in the image above. The container will run the process and then stop. No other output will display inside the terminal session.

Run a Container Interactively

Docker allows you to run a container in interactive mode. This means you can execute commands inside the container while it is still running.

By using the container interactively, you can access a command prompt inside the running container. To do so, run the following command:

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

The command prompt will change, moving you to the bash shell as in the example below.

Run a Container and Publish Container Ports

When you run a container, the only way to access the process is from inside of it. To allow external connections to the container, you have to open (publish) specific ports.

You have to add the -p option to the docker run command as well as the following information:

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

The host_ip element is optional and you don’t need to specify it when running the command.

For example, to map TCP port 80 in the container to port 8080 on the Docker host you would run:

docker container run -p 8080:80 [docker_image]

Run a Container and Mount Host Volumes

Docker containers do not save the data they produce. As soon as the process is finished, the container stops and everything inside of it is removed.

If you want to have persistent data that is stored even after the container stops, you need to enable sharing storage volumes.

For mounting volumes use the -v attribute with the specified location of the directory where you want to save the data, followed by where that data will be located inside the container.

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

The entire docker container run command is:

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

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

Once a container executes its tasks, it stops, but the file system it consists of remains on the system.

If you only need a container to execute the outlined task and have no use of it or its file system afterward, you can set it up to delete once it is done.

To run a container that will be automatically removed after exiting use the command:

docker container run --rm [docker_image]

Conclusion

Docker has earned a prominent place in development trends. The sooner you get acquainted with its command line interface the better. The first step is mastering the docker run command.

You can use this guide to learn the basics or as useful reminder when needed.