82

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?

4
  • 1
    Which part of documentation you do not understand? This is useful if you are building an image which will be used as a base to build other images Commented Jan 18, 2016 at 20:50
  • But what can I do with that. Please give me an example. Commented Jan 18, 2016 at 20:56
  • 1
    Documentation has also example. At first you can create your custom image dockerfile with required OS libraries: curl, gd, etc and add onbuild instruction to later add source code. example 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. Commented Jan 18, 2016 at 20:57
  • 1
    Sorry had to -1 this; there are plenty of examples of this. See container42.com/2014/02/06/docker-quicktip-3-onbuild for one. Commented Sep 27, 2016 at 16:00

3 Answers 3

66

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:

2
  • 'instruction' has a typo, which I would fix and not bother anyone with if StackOverflow would just allow 1-character edits.
    – Wyck
    Commented 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
30

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 and RUN 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.

0
1

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.