I read on the docker documentation how ONBUILD instruction can be used, but it is not clear at all.
Can someone please explain it to me?
3 Answers
The ONBUILD instruction is very useful for automating the build of your chosen software stack.
Example
The Maven container is designed to compile java programs. Magically all your project's Dockerfile needs to do is reference the base container containing the ONBUILD intructions:
FROM maven:3.3-jdk-8-onbuild
CMD ["java","-jar","/usr/src/app/target/demo-1.0-SNAPSHOT-jar-with-dependencies.jar"]
The base image's Dockerfile tells all:
FROM maven:3-jdk-8
RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app
ONBUILD ADD . /usr/src/app
ONBUILD RUN mvn install
There's a base image that has both Java and Maven installed and a series of instructions to copy files and run Maven.
The following answer gives a Java example:
-
'instruction' has a typo, which I would fix and not bother anyone with if StackOverflow would just allow 1-character edits.– WyckCommented Sep 2, 2018 at 0:20
-
The ONBUILD instruction adds to the image a trigger instruction to be executed at a later time. Commented Nov 22, 2020 at 19:16
As stated by the docker docs:
The ONBUILD instruction adds to the image a trigger instruction to be executed at a later time, when the image is used as the base for another build. The trigger will be executed in the context of the downstream build, as if it had been inserted immediately after the FROM instruction in the downstream Dockerfile.
So what does that mean? Let's take this Nodejs Dockerfile:
FROM node:0.12.6
RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app
ONBUILD COPY package.json /usr/src/app/
ONBUILD RUN npm install
ONBUILD COPY . /usr/src/app
CMD [ "npm", "start" ]
In your own Dockerfile, when you do FROM node:0.12.6-onbuild
you're getting an image, which means the build
command has already been run, so the instructions have ALREADY been executed as well, however all but those starting with ONBUILD
. These have been deferred to another time, when the downstream build (when your image is getting built from your own Dockerfile) uses this image as the base (FROM node:0.12.6-onbuild
).
You can’t just call
ADD
andRUN
now, because you don’t yet have access to the application source code, and it will be different for each application build.
That's right! The image containing onbuild instructions wasn't built on your machine, so it doesn't yet have access to package.json
.
Then when you build your own Dockerfile, before executing any instruction in your file, the builder will look for ONBUILD
triggers, which were added to the metadata of the parent image when it was built.
That spares you the hassle of executing these commands yourself, it really is as though these commands were written in your own Dockerfile.
Finally, they add:
You could simply provide application developers with a boilerplate Dockerfile to copy-paste into their application, but that is inefficient, error-prone and difficult to update because it mixes with application-specific code.
The thing is that if these instructions are modified in the boilerplate Dockerfile, you will have to modify them as well in your Dockerfile. But thanks to the ONBUILD
instruction, we don't have to worry about it.
None of the answers or comments provide an explanation of the reason for the existence of the ONBUILD instruction, so I'l try to come up with my own here. Please feel free to comment or edit this answer to improve it.
ONBUILD seems to be meant as a convenience for Dockerfile writers to eliminate boilerplate such as copying source files etcetera. By building FROM an image which has ONBUILD instructions, these instructions get applied to the image being built from a Dockerfile without the need to reference them in any way other than the source image FROM which an image gets built.
All this sounds like a whole lot of 'magic sauce', and IMHO one should carefully consider whether one wants that kind of thing in ones workflow. Personally, I don't. The very existence of ONBUILD forces me to carefully study the metafata for any source images I would like to build from, in case they perform some kind of 'magic' build instructions in my own build which I should be aware of. I would rather explicitly include such build instructions into my own Dockerfiles, for the sake of reproducibility and certainty about what is supposed to happen and when, not to mention security risks such as exfiltration of sensitive data.
EDIT:
Luckily there is a way to disable ONBUILD instructions: use docker build --no-on-build
when building an image
This is useful if you are building an image which will be used as a base to build other images
onbuild add src/
Later you create another dockerfile but use previously created image (FROM instruction) and stack up source code on it. So you have image with freezed OS level libraries and source code.