From f526bcdb535126c0a96a6c67413a90867b15b1ff Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 23 Sep 2020 13:05:00 +0200 Subject: [PATCH] builder: add note about alternative syntax Signed-off-by: Sebastiaan van Stijn (cherry picked from commit a4a3d2f94dae8fe7db6ae9be6574087841a68fd9) Signed-off-by: Sebastiaan van Stijn --- docs/reference/builder.md | 40 ++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index ab3c9e33d8..bbaa010bbc 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -1025,25 +1025,43 @@ The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env =`. -> **Note** +Environment variable persistence can cause unexpected side effects. For example, +setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`, +and may confuse users of your image. + +If an environment variable is only needed during build, and not in the final +image, consider setting a value for a single command instead: + +```dockerfile +RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ... +``` + +Or using [`ARG`](#arg), which is not persisted in the final image: + +```dockerfile +ARG DEBIAN_FRONTEND=noninteractive +RUN apt-get update && apt-get install -y ... +``` + +> **Alternative syntax** > -> Environment variable persistence can cause unexpected side effects. For example, -> setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`, -> and may confuse users of your image. -> -> If an environment variable is only needed during build, and not in the final -> image, consider setting a value for a single command instead: +> The `ENV` instruction also allows an alternative syntax `ENV `, +> omitting the `=`. For example: > > ```dockerfile -> RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ... +> ENV MY_VAR my-value > ``` > -> Or using [`ARG`](#arg), which is not persisted in the final image: +> This syntax does not allow for multiple environment-variables to be set in a +> single `ENV` instruction, and can be confusing. For example, the following +> sets a single environment variable (`ONE`) with value `"TWO= THREE=world"`: > > ```dockerfile -> ARG DEBIAN_FRONTEND=noninteractive -> RUN apt-get update && apt-get install -y ... +> ENV ONE TWO= THREE=world > ``` +> +> The alternative syntax is supported for backward compatibility, but discouraged +> for the reasons outlined above, and may be removed in a future release. ## ADD