Add RUN to the list of supported instructions for environment replacement

[RikiReal]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

In the Dockerfile reference in the section Environment replacement it says environment variables are not supported by the RUN instruction. However, I tried it in my Dockerfile and it worked.
Also it's used in the source code of e.g. docker-library/golang:
https://github.com/docker-library/golang/blob/db757a0fae9caa7efcd64c120c432e6f83b6eb24/Dockerfile-linux.template#L193

Location

https://docs.docker.com/engine/reference/builder/#environment-replacement

Suggestion

Add RUN to the list of supported instructions for environment variables.

[thaJeztah]

We may need some more in-depth wording for this. Unlike (e.g.) LABEL, env-var substitution in RUN is handled by the shell that's running in it, not by docker (or BuildKit).

While in most cases this would be "roughly" equivalent, there are subtle differences. Docker only knows about environment variables that are defined as part of the Dockerfile (e.g. ENV foo=bar or ARG foo=bar), as well as a PATH env-var (which is set to a default path during build). Any other environment variables are not known to Docker itself, and won't be substituted during build.

For RUN (as described above), substitution is handled by the shell (or other process) that's executing. That shell will inherit env-vars that are set in the Dockerfile, but may also have other env-vars (such as HOME) and substitute those.

/cc @dvdksn @crazy-max

[RikiReal]

The way the documentation on env-var replacement is written now, it makes me think that doing something like RUN echo $foo isn't possible.
However, reading the section for RUN it says that env-var replacement is possible. When I was just starting to work with Docker this part confused me.

I agree that a different kind of wording would be helpful. Or maybe add a reference to the RUN section of the documentation that explains env-var replacement.

[docker-robot]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment.
If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

[dvdksn]

This is now documented in the Dockerfile reference, see https://docs.docker.com/engine/reference/builder/#environment-replacement

You can also use environment variables with RUN, CMD, and ENTRYPOINT instructions, but in those cases the variable substitution is handled by the command shell, not the builder. Note that instructions using the exec form don't invoke a command shell automatically. See Variable substitution.