The ONBUILD instruction in a Dockerfile is used to set up triggers that will be executed later when the image is used as the base for another image. This instruction is particularly useful for creating base images that can automatically perform certain actions when they are used to build derivative images.
How ONBUILD Works
Trigger Setup: When you include an ONBUILD instruction in a Dockerfile, it does not execute during the build of the current image. Instead, it sets up a trigger that will be stored in the image's metadata.
Deferred Execution: These triggers are executed when the image is used as the base for another Dockerfile. The ONBUILD instructions are run immediately after the FROM instruction in the downstream Dockerfile.
Example Usage:
dockerfileCopy
# Parent Dockerfile
FROM node:14
ONBUILD COPY . /app
ONBUILD RUN npm install
In this example, the COPY and RUN instructions will not execute when building the node:14 image. Instead, they will execute when another Dockerfile uses this image as its base:
dockerfileCopy
# Child Dockerfile
FROM node:14
CMD ["node", "app.js"]
When building the child image, the COPY . /app and RUN npm install commands will be executed first.
Benefits of ONBUILD
Reduces Boilerplate: It helps in reducing repetitive code in Dockerfiles by allowing common setup steps to be defined once in a base image.
Simplifies Derived Images: Developers using the base image do not need to manually include the common setup steps, making their Dockerfiles simpler and less error-prone.
Limitations and Considerations
Lack of Flexibility: The ONBUILD instruction is not flexible and can lead to issues if the downstream build context does not match the expectations set by the ONBUILD triggers (e.g., missing files).
