Browse code

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 <spencer@spencerbrown.org>

Spencer Brown authored on 2015/07/14 22:51:32
Showing 1 changed files
... ...
@@ -21,7 +21,7 @@ executes `docker run`, she starts a process with its own file system,
21 21
 its own networking, and its own isolated process tree.  The
22 22
 [*Image*](/reference/glossary/#image) which starts the process may define
23 23
 defaults related to the binary to run, the networking to expose, and
24
-more, but `docker run` gives final control to the operator who starts
24
+more, but `docker run` gives additional control to the operator who starts
25 25
 the container from the image. That's the main reason
26 26
 [*run*](/reference/commandline/run) has more options than any
27 27
 other `docker` command.
... ...
@@ -43,11 +43,10 @@ settings affect:
43 43
  * network settings
44 44
  * runtime constraints on CPU and memory
45 45
  * privileges and LXC configuration
46
-
47
-An image developer may set defaults for these same settings when they create the
48
-image using the `docker build` command. Operators, however, can override all
49
-defaults set by the developer using the `run` options.  And, operators can also
50
-override nearly all the defaults set by the Docker runtime itself.
46
+ 
47
+An image developer may set defaults for these same settings when she creates the
48
+image using the `docker build` command. Operators can use the `run` options to override most of the
49
+defaults set by the developer. And, operators can override nearly all the defaults set by the Docker runtime itself.
51 50
 
52 51
 Finally, depending on your Docker system configuration, you may be required to
53 52
 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:
973 973
 ### EXPOSE (incoming ports)
974 974
 
975 975
 The Dockerfile doesn't give much control over networking, only providing
976
-the `EXPOSE` instruction to give a hint to the operator about what
977
-incoming ports might provide services. The following options work with
978
-or override the Dockerfile's exposed defaults:
976
+the `EXPOSE` instruction to specify incoming ports that provide services.
977
+The following `run` command options work with container networking:
979 978
 
980
-    --expose=[]: Expose a port or a range of ports from the container
981
-                without publishing it to your host
979
+    --expose=[]: Expose a port or a range of ports from the container,
980
+                in addition to ports exposed by the `EXPOSE` Dockerfile instruction
982 981
     -P=false   : Publish all exposed ports to the host interfaces
983 982
     -p=[]      : Publish a container᾿s port or a range of ports to the host
984 983
                    format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort