From 95fe3a1a937a1452b24dc8e94d6389d3dcdaf087 Mon Sep 17 00:00:00 2001 From: "Michael A. Smith" Date: Thu, 22 Jan 2015 10:09:50 -0500 Subject: [PATCH] Distinguish ENV from setting environment inline It's ambiguous to say that `ENV` is _functionally equivalent to prefixing the command with `=`_. `ENV` sets the environment for all future commands, but `RUN` can take chained commands like `RUN foo=bar bash -c 'echo $foo' && bash -c 'echo $foo $bar'`. Users with a solid understanding of `exec` may grok this without confusion, but less experienced users may need this distinction. Signed-off-by: Michael A. Smith Improve Environment Handling Descriptions - Link `ENV` and `Environment Replacement` - Improve side-effects of `ENV` text - Rearrange avoiding side effects text Signed-off-by: Michael A. Smith --- docs/sources/reference/builder.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 3931bb28a5..d0c928188d 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -113,7 +113,7 @@ was no formal definition on as to which instructions handled environment replacement at the time. After 1.3 this behavior will be preserved and canonical. -Environment variables (declared with the `ENV` statement) can also be used in +Environment variables (declared with [the `ENV` statement](#env)) can also be used in certain instructions as variables to be interpreted by the `Dockerfile`. Escapes are also handled for including variable-like syntax into a statement literally. @@ -349,9 +349,8 @@ accessible from the host by default. To expose ports to the host, at runtime, ENV = ... The `ENV` instruction sets the environment variable `` to the value -``. This value will be passed to all future -`RUN`, `ENTRYPOINT`, and `CMD` instructions. This is -functionally equivalent to prefixing the command with `=` +``. This value will be in the environment of all "descendent" `Dockerfile` +commands and can be [replaced inline](#environment-replacement) in many as well. The `ENV` instruction has two forms. The first form, `ENV `, will set a single variable to a value. The entire string after the first @@ -382,9 +381,10 @@ from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. > **Note**: -> One example where this can cause unexpected consequences, is setting -> `ENV DEBIAN_FRONTEND noninteractive`. Which will persist when the container -> is run interactively; for example: `docker run -t -i image bash` +> Environment persistence can cause unexpected effects. For example, +> setting `ENV DEBIAN_FRONTEND noninteractive` may confuse apt-get +> users on a Debian-based image. To set a value for a single command, use +> `RUN = `. ## ADD