HereDoc notation has been used for a while now in Bash, SQL, PHP, and other scripting languages. It allows a very long command to be broken down into several more readable lines while still being treated as a single command. 

For instance, in PHP, rather than having an SQL command like:

$sql = SELECT * FROM MyTable WHERE col1 < 100 and col2 > 200 ORDER BY name

Instead, you could make it more readable by splitting the components of the command across multiple lines in your file while still executing the command as one single command, something like:

$sql = <<<SQL
SELECT * FROM MyTable 
WHERE col1 < 100 and col2 > 200 
ORDER BY name
SQL;

Granted, there are a few more characters involved, but many people find this kind of format to be quicker to read and understand.

In 2021, Docker’s Buildkit started using HereDoc notation within Dockerfiles.  This allowed a Dockerfile to have what looked to be multiple commands. Still, in reality, they decomposed to a single command and, importantly, became only one layer in the resulting image rather than a layer per line in the Dockerfile.

So instead of having a Dockerfile like:

FROM docker.io/redhat/ubi9-minimal as builder

RUN microdnf update
RUN microdnf -y install gcc 
RUN microdnf -y install glibc-static 
RUN microdnf -y install procps-ng

You could instead have one like:

FROM docker.io/redhat/ubi9-minimal as builder

RUN <<EOF
microdnf update
microdnf -y install gcc 
microdnf -y install glibc-static
microdnf -y install procps-ng
EOF

These four microdnf commands are now run as one line, creating a single layer in the image rather than a layer for each RUN command as in the first Dockerfile.  Although this particular example isn’t much more readable, there are many places where a Containerfile could benefit in readability by using HereDoc syntax.

The Buldah team received several requests to incorporate this functionality into the Containerfile syntax that Buildah and Podman use. In the fall of 2023, Aditya Rajan created this Pull Request responding to this issue, initially incorporating the functionality into Buildah for the `RUN`, `COPY`, and `ADD` commands within a Containerfile. This landed in Buildah v1.33 and Podman v4.9.  However, further changes were made to the HereDoc code, which landed in Buildah v1.35 and Podman v5.0, making it fully functional.

Now, with the latest releases of Podman and Buildah, the HereDoc syntax in Containerfiles has been fully refined. Despite being available for the past few months, I think the awareness of the HereDoc syntax in Podman and Buildah’s Containerfiles is not well known. I hope this post informs you of this new syntax option that Podman and Buildah can now use and that you can use it to make the Containerfiles in your environment even more readable while potentially shrinking the number of layers in your resulting container image.