Docker run

External

• https://docs.docker.com/engine/reference/commandline/run/
• https://docs.docker.com/engine/reference/run/

Internal

• Container Lifecycle Operations
• docker create

Overview

Without any arguments except the name of image, it creates a new container based on the given image, and executes it in the foreground, connecting the current terminal's stdin/stdout/stderr to the container:

 docker run novaordis/centos-loop

The docker runtime will first attempt to use an image from the local registry, and if it does find it, it will attempt to pull it from Docker Hub and then cache locally in the local registry.

In order to run the container in the background, use -d | --detach.

The generic format of the command is:

docker run [options] <image> [command] [args...]

Example:

docker run -d --name="runloop1" -e SOME_ENV_VAR="some value" \
  busybox \
  /bin/sh -c 'i=0; while true; do echo ${i}; i=$(expr ${i} + 1);  sleep 1s; done'

A running container, either in foreground or background, can be with listed with:

docker ps

it can be stopped with:

docker stop

and then it can be restarted with:

docker start

Anything that a running container sends to stdout can be explored with docker logs.

More container operations:

Docker Client Operations

The Run Process

Container Lifecycle

Options

-i, --interactive

Start the container in interactive mode. See

Docker Concepts | Interactive Mode

-d, --detach

Start the container in detached mode and print the container ID. Note that -a|--attach and -d|--detach are mutually exclusive.

For more details see:

Docker Concepts | Detached Mode

-a, --attach

-a|--attach <stream-name>

where the stream name may be "STDIN", "stdin", "STDOUT", "stdout", "STDERR" or "stderr". Specifies what standard streams to attach to. By default, all are attached.

If multiple streams are to be attached, the syntax is:

-a STDIN -a STDOUT -a STDERR

Note that -a|--attach and -d|--detach are mutually exclusive.

For more details, see:

Docker Concepts | stdin/stdout/stderr Interaction with a Container

-t, --tty

See:

Docker Concepts | Association with a TTY Device

--entrypoint

If ENTRYPOINT is specified in the container metadata, it can be overridden on command line with:

docker run --entrypoint <other-entrypoint>

Example:

docker run --entrypoint bash -it novaordis/someimage:latest

For more details see:

ENTRYPOINT

-e, --env

-e SOME_ENV_VAR="some value" 

Set environment variables. Default values for those environment variables can be declared in the Dockerfile with ENV. Those values will be overridden by the command line value.

--name

Assign a name to the container, otherwise the name will be assigned automatically to something like "pedantic_einstein" or "competent_aryabhata".

--name="bluebox"

--restart

Configures the restart policy of the container being created. The restart policy applies when container exits.

--restart=always

See:

Start a Container Automatically

-p, --publish

-p|--publish list

Publish a container's port(s) to the host. Also see Dockerfile EXPOSE.

To publish port 8080:

docker run ... -p 8080:8080/tcp ...

Port Mapping

-p <host-port>:<container-port> 

Maps the specified container port to the specified host port.

-P, --publish-all

Publish all exposed ports to random ports. Also see Dockerfile EXPOSE.

-v, --volume

See:

Docker Storage Operations

--mount

See:

Docker Storage Operations

--rm

Automatically remove the container when it exits.

--network

The option is used to connect a container to a user-defined network. If not specified, the container is connected to the default network, which is the default "bridge" network. "Connecting" in this context means that the command associates the container with the specified network and "plugs it" into the network. After the command completes, the container's IP is routable outside to the Docker host.

docker run ... --network <network-name> ...

--storage-opt list

Storage driver options for the container. Controls the following:

Base Device Size

The amount of storage allocated to the container when the image is run (this was only tested with device-mapper):

...  --storage-opt size=20G ...

This value cannot be smaller than the default value, see device-mapper Base Device Size.

Resource Management Options

-m, --memory

The memory limit, in bytes. Apparently, that means the same amount will be allowed for "RAM" and swap, so a process can use double the specified amount, if it starts swapping. Also see Resource Management.

--link

Add link to another container.

-u, --user

Specify the username or UID and optionally the group name or GID to run the container with, using the format:

<username|uid>[:<group|gid>]

Also see:

Dockerfile USER

Troubleshooting

User has No Appropriate Permissions

The attempt to run the ps or run command under a user that has no appropriate permissions leads to:

Cannot connect to the Docker daemon. Is the docker daemon running on this host?