19.2.1 Run CLI Command

docker run is the primary command for creating and starting a container from an image. It combines docker create and docker start into a single step, pulling the specified image if it is not available locally, creating a new container from it, and immediately executing the container's default or specified command. The command offers a broad set of options that control every aspect of how the container runs: its name, networking, storage, resource limits, environment, and runtime behavior.

Basic Syntax

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

The IMAGE argument specifies the image to run. Everything after the image name is treated as the command to override the image's default CMD or ENTRYPOINT.

Simplest Invocation

docker run hello-world

Docker pulls hello-world from Docker Hub if not present locally, creates a container, runs it, and prints a confirmation message. The container exits immediately after the message is printed.

Detached Mode

By default, docker run attaches to the container's stdin, stdout, and stderr. The -d flag runs the container in the background:

docker run -d nginx:latest

The command returns the container ID and returns control to the shell. The container continues running in the background.

Naming Containers

Without --name, Docker assigns a random name. An explicit name makes management easier:

docker run -d --name web-server nginx:latest

Container names must be unique within the Docker host. Attempting to start a second container with the same name fails unless the previous container is removed first.

Interactive Mode

The -it flag combination connects the terminal to the container's stdin and allocates a pseudo-TTY, enabling interactive sessions:

docker run -it ubuntu:22.04 bash

This opens a bash shell inside a new Ubuntu container. Exiting the shell stops the container.

• -i keeps stdin open.
• -t allocates a TTY.

Automatic Removal After Exit

The --rm flag removes the container automatically once it exits:

docker run --rm myapp:1.0.0

This is particularly useful for one-off tasks, build steps, and utilities where the container's filesystem state is not needed after completion.

Port Mapping

Containers have their own network namespace. The -p flag publishes a container port to the host:

docker run -d -p 8080:80 nginx:latest

Format: host_port:container_port.

To publish on a specific host interface:

docker run -d -p 127.0.0.1:8080:80 nginx:latest

To let Docker assign a random host port:

docker run -d -p 80 nginx:latest

Inspect the assigned port with docker port web-server 80.

Volume Mounts

Bind Mount

Maps a directory from the host filesystem into the container:

docker run -d -v /host/data:/app/data myapp:1.0.0

Changes in /app/data inside the container are reflected in /host/data on the host and vice versa.

Named Volume

Uses a Docker-managed volume:

docker run -d -v mydata:/app/data myapp:1.0.0

Tmpfs Mount (in-memory)

docker run -d --tmpfs /tmp myapp:1.0.0

Environment Variables

The -e flag sets environment variables inside the container:

docker run -d -e DATABASE_URL="postgres://user:pass@db:5432/mydb" myapp:1.0.0

Multiple -e flags can be used:

docker run -d \
  -e APP_ENV=production \
  -e LOG_LEVEL=warn \
  myapp:1.0.0

Load variables from a file:

docker run -d --env-file .env myapp:1.0.0

Network Configuration

Containers are attached to the default bridge network unless specified otherwise:

docker run -d --network my-custom-network myapp:1.0.0

To use the host network (no network isolation):

docker run -d --network host nginx:latest

To run with no network access:

docker run -d --network none myapp:1.0.0

Resource Limits

Memory

docker run -d --memory 512m nginx:latest

CPU

docker run -d --cpus 1.5 myapp:1.0.0

These prevent a single container from consuming all available host resources.

Working Directory

The -w flag sets the working directory inside the container:

docker run -w /app myapp:1.0.0 ./start.sh

User

The -u flag specifies the user under which the command runs inside the container:

docker run -u 1000:1000 myapp:1.0.0
docker run -u appuser myapp:1.0.0

Hostname

docker run -d --hostname myhost.local myapp:1.0.0

Restart Policies

The --restart flag controls whether Docker restarts the container if it exits:

docker run -d --restart unless-stopped nginx:latest

Overriding the Command

Any argument after the image name overrides the image's default CMD:

docker run ubuntu:22.04 echo "Hello from Docker"

To override the ENTRYPOINT:

docker run --entrypoint /bin/sh myapp:1.0.0 -c "ls /app"

Privileged Mode

Grants the container nearly all host capabilities:

docker run --privileged myapp:1.0.0

This is required for containers that need to manage kernel modules or run nested Docker, but it removes container isolation and should be used only when necessary.

Labels

Attach metadata to the container:

docker run -d --label version=1.0.0 --label team=backend myapp:1.0.0

Labels can be used to filter containers with docker ps --filter "label=team=backend".

What Happens Internally

When docker run is invoked, the Docker daemon:

1. Checks if the image exists locally; pulls it if not.
2. Creates a new container with a writable layer on top of the image layers.
3. Applies the specified configuration (network, mounts, env, limits).
4. Starts the container's init process with the given command.
5. Attaches or detaches according to the -d flag.