Containerfile versus Dockerfile, What's the difference?

[TomSweeneyRedHat]

As I write this, it's April 20, 2021 and the latest release of Buildah stands at v1.20.1.

We've been asked a couple of times over the past few weeks, "What's the difference between a Containerfile and a Dockefile?" First off, as you can tell, they have different names. Secondly, that's it, well at least in theory. Read on for more details.

The content, commands, and any features that are usable in a Dockerfile should also be usable in a Containerfile too. That's the design goal. There may be newer options or commands in a Dockerfile that are not usable in a Containerfile. If you find any that you need that are missing, please log an issue and hopefully we can add them to the Containerfile processing code too.

The one small functional difference between the two files is how Buildah and Podman use the files. If there's a Containerfile in the context directory, Podman and Buildah will use that for the build. If there's a Dockerfile in the context directory, the build will use that if there is not a Containerfile present. If both a Containerfile and a Dockerfile are in the context directory, Podman and Buildah will use the Containerfile and will ignore the Dockerfile. Then if you use the --file option, you can name the file pretty much anything you want.

Given all that, at some point in time in the future if we find commands that would be helpful in a Containerfile that are not present in a Dockerfile, then if the community desires, they might be added to the Containerfile processing. There are currently no plans for that and (KOD), I don't anticipate changes like that in the foreseeable future.

Hope that helps to explain the differences between a Containerfile and a Dockefile for Podman and Buildah.

[TomSweeneyRedHat]

@isavl thanks for the poke via your recent issue, a little more detail on Containerfile vs Dockerfile if you're interested.

[rhatdan]

LGTM

[j3mdamas]

Hi,
I have been doing some research, but maybe you can point me in the right direction.
buildah builds OCI-compliant images. There are good references for it: https://github.com/opencontainers/image-spec/blob/main/spec.md. But when trying to have a good reference for Containerfile, I always end up using this. Is that the right reference for the file format? Is there some OCI-ish reference? I could not find it.

[TomSweeneyRedHat]

@j3mdamas, the innards of a Containerfile and a Dockerfile should be equivalent, so the Dockerfile Reference page that you pointed to works. The only other document that we have is the Containerfile manpage, but that's admittedly not as detailed.

[j3mdamas]

I see, thanks for the feedback :)

[imphil]

With rather sparse documentation on what syntax buildah vs. buildkit support, I have a similar question: How does buildah deal with external frontends, specified through # syntax=docker/dockerfile:1.2? Does it ignore this statement? And if so, what version of the Dockerfile syntax does buildah support?

[rhatdan]

Buildah is attempting to follow buildkit syntax. We ignore the syntax flag.

[imphil]

Thanks! Is there documentation somewhere what version of the syntax a particular buildah version supports?

[rhatdan]

No we don't track it that closely, although I would guess you could approximately line up the support that buildkit had.
The bottom line is we add features to Buildah when people realize that a Dockerfile works on Docker but not on buildah and then we add support, if their is a difference between old Docker and Buildkit, then we go with buildkits version.