FROM foo AS builder
.. build steps
FROM foo
COPY --from=builder generated-file target
(I hope I got that right; on a phone and been a while since I did this from scratch, but you get the overall point)Say `apt install build-essential libvips` from the OP, it's not obvious to me what files libvps is adding. I suppose there's probably an incantation for that? What about something that installs a binary? Seems like a pain to chase down everything that's arbitrarily touched by an apt install, am I missing some tooling that would tame that pain?
It is of course possible to do for a single project with a bit of effort: build each stage with a remote OCI cache source, push the cash there after. But... that sucks.
What you want is the `max` cache type in buildkit[1]. Except... not much supports that yet. The native S3 cache would also be good once it stabalizes.
It worked wonders for us, on a cache hit the build time is reduced from 10 to 1,5 minutes.
It is really weird looking at Dockerfiles for the first time seeing all of the `&% \` bash commands chained together.
https://docs.docker.com/develop/develop-images/dockerfile_be...
> Official Debian and Ubuntu images automatically run apt-get clean, so explicit invocation is not required.
RUN apt-get update -qq && \
apt-get install -y build-essential libvips && \
apt-get clean && \
rm -rf /var/lib/apt/lists/* /usr/share/doc /usr/share/man
I'd do: RUN apt-get update -qq && \
apt-get install -y build-essential libvips && \
rm -rf /var/lib/apt/lists/*rm -rf isn't configuration management, it's system entropy increasing leaving users scrambling to reinstall the world.
If people don't want docs, then distro vendors should package them separately and make them recommended packages.
"I recommend avoiding Ubuntu because it violates the principle of dev - prod parity."
What exactly is the problem? Would you please like to provide sources to this issue / some explanation / any helpful content? THANKS!
It's good to have a slim script but also to have an unslim when you need manpages or locales.
FROM the_source_image as builder
RUN build.sh
FROM the_source_image
COPY --from=builder /app/artifacts /app/
CMD ....
i'm not sure if you can really call it the new best practice though, its been the default for ... a very long time at this point.For example, say I have my own Ubuntu image that is based on one of the official ones, but adds a bit of common configuration or tools and so on, on which I then build my own Java image using the package manager (not unlike what Bitnami do with their minideb, on which they then base their PostgreSQL and most other container images).
So I might have something like the following in the Ubuntu image Dockerfile:
RUN apt-get update && apt-get install -y \
curl wget \
net-tools inetutils-ping dnsutils \
supervisor \
&& apt-get clean && rm -rf /var/lib/apt/lists /var/cache/apt/*
But then, if I want to install additional software, I need to fetch the package list anew downstream: FROM my-own-repo/ubuntu
RUN apt-get update && apt-get install -y \
openjdk-17-jdk-headless \
&& apt-get clean && rm -rf /var/lib/apt/lists /var/cache/apt/*
As opposed to being able to just leave the cache files in the previous layers/images, then remove them in a later layer and just do something like: docker build -t my_optimized_java_image -f java.Dockerfile --purge-deleted-files .
or maybe
docker build -t my_regular_java_image -f java.Dockerfile .
purge-deleted-files -t my_regular_java_image -o my_optimized_java_image
Which would then work backwards from the last layer and create copies of all of the layers where files have been removed/masked (in the later layers) to use instead of the originals. Thus if I'd have 10 different images that need to use apt to install stuff while building them, I could leave the cache in my own Ubuntu image and then just remove it for whatever I want to consider the "final" images that I'll ship, which would then alter the contents of the included layers to purge deleted files.There's little reason why these optimized layers couldn't be shared across all 10 of those "final" images either: "Hey, there's these optimized Ubuntu image layers without the package caches, so we'll use it for our .NET, Java, Node and other images" as opposed to --squash which would put everything in a single large layer, thus removing the benefits from the shared layers of the base Ubuntu image and so on.
Who knows, maybe someone will write a tool like that some day.
https://www.docker.com/blog/introduction-to-heredocs-in-dock...
This is great and really makes things way simpler. Thanks!
Many other dockerfile build tools still don't support it, e.g. buildah (see https://github.com/containers/buildah/issues/3474)
Useful now if you have control over the environment your images are being built in, but I'm excited to the future where it's commonplace!
You can put stuff in a script file and just run that script too.
Tracking for this: https://github.com/docker/buildx/issues/1104
this has been a serious pain in my side for a while, both for my own debugging and for telling people I try to help "you're gonna have to start over and do X or this will take hours longer".
If you want to reduce layer/image size, then I think [1] "multi-stage builds" is a good option
You can use HEREDOCS to combo together commands that make sense in a layer, ensure your layers are ordered such that the more-frequently changing ones are further on in your Dockerfile when possible (this will also speed up your builds, ensuring as many caches as possible are more likely to be valid), and use mutli-stage builds on top of that to really pare it down to the bare necessities.
Is it though? From the post:
RUN <<EOF apt-get update apt-get upgrade -y apt-get install -y ... EOF
It may be due to my ninja level abilities to dodge learning more advanced shell mastery for decades, but to me it looks haphazard and error prone. Are the line breaks semantic, or is it all a multiline string? Is EOF a special end-of-file token, or a variable, if so what’s it’s type? Where is it documented? Is the first EOF sent to stdin, if so why is that needed? What is the second EOF doing? I can usually pick up a new imperative language quickly, but I still feel like an idiot when looking at shell.
<<XYZ
...
XYZ
syntax for multi-line strings is worth learning since it is used in shell, ruby, php, and others. See https://en.m.wikipedia.org/wiki/Here_document . You get to pick the "EOF" delimiter.> > Nice syntax
> Is it though?
The usual alternative is to use a backslash at the end of each line, creating a line continuation. This swallows the newline, so you also need a semicolon to mark the end of each command*. Forgetting the semicolon leads to weird errors. Also, while Docker supports line continuations interspersed with comments, sh doesn't, so if such a command contains comments it can't be copied into sh.
The new heredoc syntax doesn't have any of these issues. I think it is infinitely better.
(There is also JSON-style syntax, but it requires all backslashes to be doubled, and it is less popular.)
*In practice "&&" is normally used rather than ";" in order to stop the build if any command fails (otherwise sh only propagates the exit status of the last command). This is actually a small footgun with the heredoc syntax, because it is tempting to just use a newline (equivalent to a semicolon). The programmer must remember to type "&&" after each command, or use `set -e` at the start of the RUN command, or use `SHELL ["/bin/sh", "-e", "-c"]` at the top of the Dockerfile. Sigh...
> Are the line breaks semantic, or is it all a multiline string?
The line breaks are preserved ("what you see is what you get").
> Is EOF a special end-of-file token
You can choose which token to use (EOF is a common convention, but any token can be used). The text right after the "<<" indicates which token you've chosen, and the heredoc is terminated by the first line that contains just that token.
This allows you to easily create a heredoc containing other heredocs. Can you think of any other quoting syntax that allows that? (Lisp's quote form comes to mind.)
> Where is it documented?
The introduction blog post has already been linked. The reference documentation (https://github.com/moby/buildkit/blob/master/frontend/docker...) mentions but doesn't have a formal specification (unfortunately this is a wider problem for Dockerfiles, see https://supercontainers.github.io/containers-wg/ideas/docker... instead it links to the sh syntax (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V...), on which the Dockerfile heredoc syntax is based.
(Good luck looking up this syntax if you don't know what it's called. But that's the same for most punctuation-based syntax.)
> This actually leads to a small footgun with the heredoc syntax: it allows the programmer to use just a newline, which is equivalent to a semicolon and means the exit status will be ignored for all but the last command.
This sounds like a medium-large caliber footgun to me, and while I don’t expect Docker to fix sh, it could perhaps either set sane defaults or decouple commands from creating layers? Or why not simply support decent lists of commands if this is such a common use case?
> This allows you to easily create a heredoc containing other heredocs.
Hmm, what’s the use-case for that? The only effect for the programmer would be to change the escape sequence, no?
Ha ha, I guess footgun sizes are all relative. The quirky error handling of sh is "well-known", and one of the first pieces of advice for improving safety is usually to insert `set -e` at the top of every shell script (which mostly fixes this issue). So I don't think of heredocs in Dockerfiles as a large footgun, but rather as a small footgun that arises due to the coincidental and minor interaction between heredocs and the "well-known" error handling footgun.
> > This allows you to easily create a heredoc containing other heredocs.
> Hmm, what’s the use-case for that? The only effect for the programmer would be to change the escape sequence, no?
It can be useful to embed entire files within a script (e.g. when writing a script that pre-populates a directory with some small files). With most quoting schemes, you'd have to escape special characters that appear in those files. But with heredocs, you just have to pick a unique token and then you can include the files verbatim.
(Picking a token that doesn't appear as a line within the files can be a little tricky, but in many cases it's not a problem; for example if the files to be included are trustworthy, it should be enough to use a token that includes the script's name. On the other hand if the data is untrusted, you'd have to generate an unguessable nonce using a CSPRNG. But at that point it's easier to base64-encode the data first, in which case the token can be any string which never appears in the output of base64, for example ".".)
1) a layer is essentially a docker image in itself and
2) a layer is as static as the image itself
3) Docker images ship with all layers
Thanks jchw!
Example: in the last few years docker compose files have gone from version 2 to version 3 (missing tons of great v2 features in the name of simplification) to the newest, unnamed unnumbered version which is a merging of versions 2 and 3.
Externally managed caches don't have a lifecycle controlled or invalidated by changes in Dockerfiles, or by docker cache-purging commands like "system prune".
That means you have to keep track of those caches yourself, which can be a pain in complex, multi-contributor environments with many layers and many builds using the same caches (intentionally or by mistake).
Caveat: it doesn't work on Fly.io. They seem to be having some issue with OCI manifests: https://github.com/containers/skopeo/issues/1881 . They're also having issues with new docker versions pushing from CI: https://community.fly.io/t/deploying-to-fly-via-github-actio... ... the timing of this post seems weird.
FWIW the article says
> create a Docker image, also known as an OCI image
I don't think this is quite right. From my investigation, Docker and OCI images are basically content addressed trees, starting with a root manifest that points to other files and their hashes (root -> images -> layers -> layer configs + files). The OCI manifests and configs are separate to Docker manifests and configs and basically Docker will support both side by side.
It isn't explicitly explained, but the reason why it must be in this command and not separated out is because each command in a dockerfile creates a new "layer". Removing the files in another command will work, but it does nothing to decrease the overall image size: as far as whatever filesystem driver you're using is concerned, deleting files from earlier layers is just masking them, whereas deleting them before creating the layer prevents them from ever actually being stored.