ONBUILD

ONBUILD is a Dockerfile instruction that defines a trigger to be executed when the image is used as a base for another image. It lets a base image specify build steps that should automatically run in descendant images, enabling a form of inheritance for Docker images.

Mechanism: When you build a child image with FROM base-image, the ONBUILD instructions in the base are not executed during the base’s own build. Instead, they are recorded as triggers and executed in the context of the child image’s build. The triggered instructions run at build time of the child, and their effects apply to the child image, not to the base.

Common use: to automate setup for multiple derived images, such as installing common dependencies, copying scaffolding, or enforcing a project layout. For example: Base image Dockerfile: FROM python:3.11 ONBUILD COPY . /app ONBUILD RUN pip install -r /app/requirements.txt. A downstream image built from this base that contains a requirements file will automatically copy that file into /app and install the dependencies as part of its build.

Cautions: ONBUILD can surprise downstream users by executing instructions they did not explicitly write in their Dockerfile, which can make builds slower or fail unexpectedly. For this reason, it is generally discouraged in widely distributed base images and is more suitable for controlled internal image pipelines. Documentation and clear communication are important when using ONBUILD.