Docker documentation erroneously claims Here-Documents being a Docker feature – they are a shell feature instead

[SetTrend]

Is this a docs issue?

• [X] My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

The Docker documentation claims that Here-Documents are a Docker feature that may be used with every shell.

However, Here-Documents do not work with Windows cmd or PowerShell.

Location

https://docs.docker.com/reference/dockerfile/#here-documents

Suggestion

It should be explicitly mentioned in the documentation that Here-Documents are a shell feature that is only available to shells supporting this feature and it's just coincidentally available to the Dockerfile RUN instruction due to the shell supporting this feature.

[dvdksn]

This section refers to heredocs in Dockerfiles, and has nothing to do with shells. It refers to BuildKit's ability to interpret multi-line RUN and COPY instructions by using heredoc delimiters for those instructions, as shown in the examples.

Are you observing some kind of issue with heredocs in Dockerfiles?

[SetTrend]

Yet, apparently, the Here-Document is interpreted by the shell, not by the Dockerfile:

When I'm using this Dockerfile:

# escape=`
FROM mcr.microsoft.com/windows/servercore:20H2
RUN <<EOT
  ECHO.
EOT

… I'm getting this build output:

Sending build context to Docker daemon ...
Step 1/2 : FROM mcr.microsoft.com/windows/servercore:20H2
 ---> d7c03b5bcc73
Step 2/2 : RUN <<EOT
 ---> Running in 1e07112fa6d9
<< was unexpected at this time.
The command 'cmd /S /C <<EOT' returned a non-zero code: 1

[dvdksn]

@tonistiigi is this working as intended? I would've thought that the heredocs for RUN are shell-agnostic, but looks like they aren't. Do Windows shells have an alternative syntax, e.g. PowerShell here-strings? https://devblogs.microsoft.com/scripting/powertip-use-here-strings-with-powershell/

[docker-robot[bot]]

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

[tonistiigi]

@dvdksn If the heredoc starts with a shebang (on unix) then the heredoc is turned into script that is then executed (no shell needed). Otherwise the bytes of the heredoc are sent to the shell that needs to be able to handle the multi-line input.

from alpine
run <<eot
#!/usr/bin/env ash
ps aux
eot

run <<eot
ps aux
eot

run ash <<eot
ps aux
eot

#6 [2/4] RUN <<eot (#!/usr/bin/env ash...)
#6 0.141 PID   USER     TIME  COMMAND
#6 0.142     1 root      0:00 ash /dev/pipes/eot
#6 0.142     7 root      0:00 ps aux
#6 DONE 0.2s

#7 [3/4] RUN <<eot (ps aux)
#7 0.209 PID   USER     TIME  COMMAND
#7 0.209     1 root      0:00 /bin/sh -c ps aux
#7 0.209     7 root      0:00 ps aux
#7 DONE 0.2s

#8 [4/4] RUN ash <<eot
#8 0.215 PID   USER     TIME  COMMAND
#8 0.215     1 root      0:00 /bin/sh -c ash <<eot ps aux eot
#8 0.215     7 root      0:00 ash
#8 0.215     8 root      0:00 ps aux
#8 DONE 0.2s