From 9faf4cef969bce87e7100b64051dac23d3b7d58c Mon Sep 17 00:00:00 2001 From: Spencer Brown Date: Tue, 14 Jul 2015 06:51:32 -0700 Subject: [PATCH 1/2] run.md: --expose does NOT override Dockerfile EXPOSE run.md states that the operator can override all defaults set in the Dockerfile, and explicitly says that `--expose` overrides the `EXPOSE` instruction. Neither of these are true. An `EXPOSE` instruction cannot be overridden, `--expose` can only add additional exposed ports. This change fixes the instructions, and also takes the liberty of crisping up the grammar and phrasing in a place or two. Signed-off-by: Spencer Brown Upstream-commit: 6dd84ba2ab6416a71e58ca32263c6f51a197aed0 Component: engine --- components/engine/docs/reference/run.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/components/engine/docs/reference/run.md b/components/engine/docs/reference/run.md index 5ac3dfc82e..663937666b 100644 --- a/components/engine/docs/reference/run.md +++ b/components/engine/docs/reference/run.md @@ -21,7 +21,7 @@ executes `docker run`, she starts a process with its own file system, its own networking, and its own isolated process tree. The [*Image*](/reference/glossary/#image) which starts the process may define defaults related to the binary to run, the networking to expose, and -more, but `docker run` gives final control to the operator who starts +more, but `docker run` gives additional control to the operator who starts the container from the image. That's the main reason [*run*](/reference/commandline/run) has more options than any other `docker` command. @@ -43,11 +43,10 @@ settings affect: * network settings * runtime constraints on CPU and memory * privileges and LXC configuration - -An image developer may set defaults for these same settings when they create the -image using the `docker build` command. Operators, however, can override all -defaults set by the developer using the `run` options. And, operators can also -override nearly all the defaults set by the Docker runtime itself. + +An image developer may set defaults for these same settings when she creates the +image using the `docker build` command. Operators can use the `run` options to override most of the +defaults set by the developer. And, operators can override nearly all the defaults set by the Docker runtime itself. Finally, depending on your Docker system configuration, you may be required to preface each `docker` command with `sudo`. To avoid having to use `sudo` with @@ -973,12 +972,11 @@ or two examples of how to pass more parameters to that ENTRYPOINT: ### EXPOSE (incoming ports) The Dockerfile doesn't give much control over networking, only providing -the `EXPOSE` instruction to give a hint to the operator about what -incoming ports might provide services. The following options work with -or override the Dockerfile's exposed defaults: +the `EXPOSE` instruction to specify incoming ports that provide services. +The following `run` command options work with container networking: - --expose=[]: Expose a port or a range of ports from the container - without publishing it to your host + --expose=[]: Expose a port or a range of ports from the container, + in addition to ports exposed by the `EXPOSE` Dockerfile instruction -P=false : Publish all exposed ports to the host interfaces -p=[] : Publish a container᾿s port or a range of ports to the host format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort From 1a9ed3e5c073d8058d27b88213d020e0cea15cb7 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 18 Aug 2015 00:16:11 +0200 Subject: [PATCH 2/2] Add gists provided by Mary This adds the example gists, provided by Mary Anthony, also fixes a link to the old /terms/ Signed-off-by: Sebastiaan van Stijn Upstream-commit: 35cbcc2fc1334b14a6aa9a1adf432c0ee80fd108 Component: engine --- components/engine/docs/reference/run.md | 119 ++++++++++++++---------- 1 file changed, 69 insertions(+), 50 deletions(-) diff --git a/components/engine/docs/reference/run.md b/components/engine/docs/reference/run.md index 663937666b..caab5b4c94 100644 --- a/components/engine/docs/reference/run.md +++ b/components/engine/docs/reference/run.md @@ -16,15 +16,14 @@ parent = "mn_reference" # Docker run reference -**Docker runs processes in isolated containers**. When an operator -executes `docker run`, she starts a process with its own file system, -its own networking, and its own isolated process tree. The -[*Image*](/reference/glossary/#image) which starts the process may define -defaults related to the binary to run, the networking to expose, and -more, but `docker run` gives additional control to the operator who starts -the container from the image. That's the main reason -[*run*](/reference/commandline/run) has more options than any -other `docker` command. +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. ## General form @@ -32,27 +31,33 @@ The basic `docker run` command takes this form: $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] -To learn how to interpret the types of `[OPTIONS]`, -see [*Option types*](/reference/commandline/cli/#option-types). - -The `run` options control the image's runtime behavior in a container. These -settings affect: +The `docker run` command must specify an [*IMAGE*](/reference/glossary/#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 * privileges and LXC configuration - -An image developer may set defaults for these same settings when she creates the -image using the `docker build` command. Operators can use the `run` options to override most of the -defaults set by the developer. And, operators can override nearly all the defaults set by the Docker runtime itself. -Finally, depending on your Docker system configuration, you may be required to -preface each `docker` 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. +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*](/reference/commandline/cli/run/) has more options than any +other `docker` command. + +To learn how to interpret the types of `[OPTIONS]`, see [*Option +types*](/reference/commandline/cli/#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 @@ -971,45 +976,59 @@ or two examples of how to pass more parameters to that ENTRYPOINT: ### EXPOSE (incoming ports) -The Dockerfile doesn't give much control over networking, only providing -the `EXPOSE` instruction to specify incoming ports that provide services. The following `run` command options work with container networking: - --expose=[]: Expose a port or a range of ports from the container, - in addition to ports exposed by the `EXPOSE` Dockerfile instruction + --expose=[]: Expose a port or a range of ports inside the container. + These are additional to those exposed by the `EXPOSE` instruction -P=false : Publish all exposed ports to the host interfaces -p=[] : Publish a container᾿s port or a range of ports to the host format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort - Both hostPort and containerPort can be specified as a range of ports. - When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`) - When specifying a range for hostPort only, the containerPort must not be a range. In this case the container port is published somewhere within the specified hostPort range. (e.g., `-p 1234-1236:1234/tcp`) + Both hostPort and containerPort can be specified as a + range of ports. When specifying ranges for both, the + number of container ports in the range must match the + number of host ports in the range, for example: + -p 1234-1236:1234-1236/tcp + + When specifying a range for hostPort only, the + containerPort must not be a range. In this case the + container port is published somewhere within the + specified hostPort range. (e.g., `-p 1234-1236:1234/tcp`) + (use 'docker port' to see the actual mapping) + --link="" : Add link to another container (:alias or ) -As mentioned previously, `EXPOSE` (and `--expose`) makes ports available -**in** a container for incoming connections. The port number on the -inside of the container (where the service listens) does not need to be -the same number as the port exposed on the outside of the container -(where clients connect), so inside the container you might have an HTTP -service listening on port 80 (and so you `EXPOSE 80` in the Dockerfile), -but outside the container the port might be 42800. +With the exception of the `EXPOSE` directive, an image developer hasn't +got much control over networking. The `EXPOSE` instruction defines the +initial incoming ports that provide services. These ports are available +to processes inside the container. An operator can use the `--expose` +option to add to the exposed ports. -To help a new client container reach the server container's internal -port operator `--expose`'d by the operator or `EXPOSE`'d by the -developer, the operator has three choices: start the server container -with `-P` or `-p,` or start the client container with `--link`. +To expose a container's internal port, an operator can start the +container with the `-P` or `-p` flag. The exposed port is accessible on +the host and the ports are available to any client that can reach the +host. -If the operator uses `-P` or `-p` then Docker will make the exposed port -accessible on the host and the ports will be available to any client that can -reach the host. When using `-P`, Docker will bind the exposed port to a random -port on the host within an *ephemeral port range* defined by -`/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host -ports and the exposed ports, use `docker port`. +The `-P` option publishes all the ports to the host interfaces. Docker +binds each exposed port to a random port on the host. The range of +ports are within an *ephemeral port range* defined by +`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to +explicitly map a single port or range of ports. -If the operator uses `--link` when starting the new client container, +The port number inside the container (where the service listens) does +not need to match the port number exposed on the outside of the +container (where clients connect). For example, inside the container an +HTTP service is listening on port 80 (and so the image developer +specifies `EXPOSE 80` in the Dockerfile). At runtime, the port might be +bound to 42800 on the host. To find the mapping between the host ports +and the exposed ports, use `docker port`. + +If the operator uses `--link` when starting a new client container, then the client container can access the exposed port via a private -networking interface. Docker will set some environment variables in the -client container to help indicate which interface and port to use. +networking interface. Docker will set some environment variables in the +client container to help indicate which interface and port to use. For +more information on linking, see [the guide on linking container +together](/userguide/dockerlinks/) ### ENV (environment variables)