Create Docker Containers Using the Command Line Interface

Whether you are new to Docker and are learning about containers, or you are testing out a new image before incorporating it into your development environment, one of the first things that you’ll do is run them to inspect how they work. This post will guide you through some of the more common docker run commands to help you both test and create your own Docker containers using the command line.

Basic Syntax

Before we jump in, let’s understand the basic syntax of the docker run command:

docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARGS]

[OPTIONS] refers to the CLI options that modify the docker run command. For example, this includes giving a name to your Docker container, setting ports, etc. The next component is IMAGE[:TAG]. Image is required, and it is the name of the Docker image that you will run (e.g. “hello-world,” “ubuntu”). You can additionally provide a tag such as latest.

The next argument is [COMMAND] which specifies a command to have the container run. Note that this will override the default command as defined by the image’s Dockerfile. Finally, you can provide arguments to your specified command with [ARGS].

Foreground vs. Background

The first option you must decide on when calling docker run is whether to run the image in the foreground or background. To help you make this decision, use the following flow chart:

Typically, commands that run in the foreground should use the --rm flag so that the container is cleaned up after the command has completed. If you are testing a long-running command, typing Ctrl+C will exit out of the container.

In order to run a container in the background, use the -d flag. It is recommended to name your container using the --name={container_name} flag when running a container in the background so that it can be referred to by name in follow-on commands.

• Foreground Examples
  • Simple Command: docker run --rm hello-world
  • Testing Configuration: docker run --rm -p 80:80 nginx
• Background Examples
  • Long Running Command: docker run --d -p 80:80 --name=mynginx nginx
  • Now you can control this container using its name:
    • Get Logs: docker logs mynginx
    • Start Container: docker start mynginx
    • Stop Container: docker stop mynginx
    • Delete Container: docker rm mynginx

Host Ports and Host Volumes

Two of the most important ways to interact with docker containers are over the network by sharing host ports, and by sharing volumes from the host.

To map a port on the host to a port on the container, use the flag -p [hostPort:containerPort] — This flag can appear multiple times to map multiple ports.

To map a volume on the host to a directory on the container, use the flag -v [host-src:container-dest:options] — This flag can appear multiple times to map multiple host volumes.

• Port Mapping Example

  • docker run --rm -p 8080:80 -p 8081:81 nginx
  • Maps port 8080 on the host to port 80 in the container
  • Maps port 8081 on the host to port 81 in the container

• Volume Mapping Example

  • docker run --rm -v /home/ubuntu/website:/var/www:rw -v /home/ubuntu/www.conf:/etc/nginx/conf.d/www.conf:ro nginx
  • Maps directory /home/ubuntu/website on the host to /var/www in the container. Changes can be made on both host and container since it uses read-write rw option
  • Maps file /home/ubuntu/www.conf on the host to /etc/nginx/conf.d/www.conf in the container. Changes can only be made on host since container has read-only ro option

Environment Variables

Environment variables allow for configuration of the software running inside the Docker container.

To set an environment variable inside the container, use the flag -e "NAME=VALUE" — This flag can appear multiple times to set multiple environment variables.

• Environment Variable Example

  • docker run --rm -e "MYSQL_ROOT_PASSWORD=test" mysql
  • Sets the mysql root password to “test” in the official mysql image

Debugging by Dropping a Shell

Sometimes it is challenging to get a Docker image running with the default command. One easy way to debug an issue is by dropping a shell into a docker container.

First, inspect the Docker image’s normal command by running docker inspect -f '{{.Config.Cmd}}' [image:tag]

Next, to drop a shell, provide the -it flags and change the command by passing the name of a shell, such as sh as the final argument

• Inspect the Docker Image’s normal command

  • docker inspect -f '{{.Config.Cmd}}' nginx
  • The “nginx” image’s normal command is: nginx -g daemon off;

• Drop a Shell

  • docker run --rm -it nginx sh
  • Drops us into the sh shell
  • We can now run the original command nginx -g daemon off; inside of the container to debug it

These docker run commands can go a long way in testing, creating, and debugging Docker containers. Now that you know how to create Docker containers using the CLI, check out our Dockerfiles Guide to build your own Docker images.