Estimated reading time: 62 minutes
Docker run reference
Docker runs processes in isolated containers. A container is a
process which runs on a host. The host may be local or remote. When
an operator executes docker run, the container process that runs is
isolated in that it has its own file system, its own networking,
and its own isolated process tree separate from the host.
This page details how to use the docker run command to define the
container’s resources at runtime.
The basic docker run command takes this form:
$ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]
The docker run command must specify an IMAGE to derive the container from. An image developer can define image
defaults related to:
- detached or foreground running
- container identification
- network settings
- runtime constraints on CPU and memory
With the docker run [OPTIONS] an operator can add to or override
the image defaults set by a developer. And, additionally, operators
can override nearly all the defaults set by the Docker runtime
itself. The operator’s ability to override image and Docker runtime
defaults is why run has more options than any other docker command.
To learn how to interpret the types of [OPTIONS], see Option types.
Note: Depending on your Docker system configuration, you may be
required to preface the docker run command with sudo. To avoid
having to use sudo with the docker command, your system
administrator can create a Unix group called docker and add users
to it. For more information about this configuration, refer to the
Docker installation documentation for your operating system.
Operator exclusive options
Only the operator (the person executing docker run) can set the
- Detached vs foreground
- Container identification
- Name (--name)
- PID equivalent
- IPC settings (--ipc)
- Network settings
- Restart policies (--restart)
- Clean up (--rm)
- Runtime constraints on resources
- Runtime privilege and Linux capabilities
Detached vs foreground
When starting a Docker container, you must first decide if you want
to run the container in the background in a detached” mode or in
the default foreground mode:
-d=false: Detached mode: Run container in the background, print new
To start a container in detached mode, you use -d=true or just -d
option. By design, containers started in detached mode exit when
the root process used to run the container exits, unless you also
specify the --rm option. If you use -d with --rm, the container is
removed when it exits or when the daemon exits, whichever happens first.
Do not pass a service x start command to a detached container. For
example, this command attempts to start the nginx service.
$ docker run -d -p 80:80 my_image service nginx start
This succeeds in starting the nginx service inside the container.
However, it fails the detached container paradigm in that, the root
process (service nginx start) returns and the detached container
stops as designed. As a result, the nginx service is started but
could not be used. Instead, to start a process such as the nginx
web server do the following:
$ docker run -d -p 80:80 my_image nginx -g 'daemon off;'
To do input/output with a detached container use network
connections or shared volumes. These are required because the
container is no longer listening to the command line where docker
run was run.
To reattach to a detached container, use docker attach command.
In foreground mode (the default when -d is not specified), docker
run can start the process in the container and attach the console
to the process’s standard input, output, and standard error. It can
even pretend to be a TTY (this is what most command line
executables expect) and pass along signals. All of that is
-a=Attach to `STDIN`, `STDOUT` and/or `STDERR` -tAllocate a
pseudo-tty --sig-proxy=true: Proxy all received signals to the
process (non-TTY mode only) -iKeep STDIN open even if not attached
If you do not specify -a then Docker will attach to both stdout and
stderr . You can specify to which of the three standard streams
(STDIN, STDOUT, STDERR) you’d like to connect instead, as in:
$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash
For interactive processes (like a shell), you must use -i -t
together in order to allocate a tty for the container process. -i