Docker ONBUILD Instruction Explained With Practical Examples

In this blog you will learn all about the Docker ONBUILD instruction with practical examples.

What is ONBUILD?

The ONBUILD instruction sets triggers that are executed when the image is used as a base for other images. You can compare this to a startup script in a VM image, which runs automatically when the VM is started with that image.

This is useful for images designed to be extended by other Dockerfiles

Let’s understand it with a real-world use case:

Imagine you are a DevOps engineer managing multiple Python Flask projects for your team.

To build a Flask application, you need the python code and a requirements.txt file, where you define the app's dependencies.

You want to ensure every project team uses the same commands to install dependencies and the same file paths in the Dockerfile for copying files.

One approach is to ask teams to follow standard documentation, but this can result in inconsistencies between teams.

Alternatively, you can use the ONBUILD instruction to standardize dependency installation and file copying.

Here’s how it works:

1. ONBUILD instructions store commands in the image metadata of the base image.
2. When a child image is built using a base image with ONBUILD instructions, Docker retrieves these stored instructions from the base image’s metadata and executes them in the order they were defined.

Instead of duplicating steps like dependency installation and file copying in every Dockerfile, you can create a base image (e.g., flask-base:1.0) with ONBUILD instructions.

For example,

ONBUILD COPY requirements.txt /app/
ONBUILD RUN pip install --no-cache-dir -r requirements.txt
ONBUILD COPY . /app

When another Dockerfile uses the flask-base:1.0 image as its base, the ONBUILD instructions will automatically execute. This eliminates the need to duplicate steps like copying the requirements.txt file, installing dependencies, and copying application files to the /app directory in every Dockerfile used by different teams.

Teams using the base image only need to ensure that the requirements.txt file and the codebase are present in the correct folder.

This ensures:

• Developers to standardize tasks (e.g., copying files, installing dependencies) across multiple child images.
• Teams using the base image only need to provide the required files (e.g., requirements.txt and codebase) in the expected structure; the rest is automated.

ONBUILD Practical Example

Now, we’ll look at a practical example that showcases the use of ONBUILD instruction.

We will use a simple Python Flask application for this demo.

Step 1: Create Base Image Dockerfile

Create a Dockerfile and copy the below Dockerfile content.

FROM python:3.11-slim

WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

EXPOSE 5000

# Add ONBUILD instructions for dependency installation and file copying

ONBUILD COPY requirements.txt /app/
ONBUILD RUN pip install --no-cache-dir -r requirements.txt
ONBUILD COPY . /app

CMD ["python", "app.py"]

In this Dockerfile, we added ONBUILD instructions to automate certain steps for child images:

1. Copy requirements.txt to the /app directory from the build context.
2. Install dependencies by running pip install using the requirements.txt file.
3. Copy all files from the build context to the /app directory.

Step 2: Build the Base Image

Run the following command to build the application.

docker build -t flask-base:1.0 .

This command creates an image named flask-base with the tag 1.0 using the Dockerfile instructions above.

Step 3: Create Required App Files

Now lets create required app filed to test the base image with ONBUILD instructions to build and run flask application.

Create app.py

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello, World!'

if __name__ == '__main__':
    app.run(host='0.0.0.0')

Create requirements.txt with the following.

Flask==2.2.5

Step 4: Creating Child Image Dockerfile

Each Flask project can now use the flask-base image as its base. The ONBUILD instructions ensure that:

• requirements.txt is automatically copied and dependencies are installed.
• Application code is copied into the container.

Create a Dockerfile with the following content in the same folder where you have app.py and requirements.txt.

FROM flask-base:1.0

CMD ["python", "app.py"]

As you can see, we are not specifying any commands related to dependency installation or copying the requirements or code files because these are part of the ONBUILD instructions in the base image.

Build the app child image using the following command.

docker build -t flask-app:1.0 .

When building the app image, Docker will display messages for the triggered ONBUILD instructions:

In the follwing output, the highlighted steps showcase the use of ONBUILD instructions:

These steps are executed automatically because of the ONBUILD instructions defined in the base image (flask-base:1.0). The ONBUILD triggers these actions when building the child image, even though they are not explicitly stated in your Dockerfile

Step 5: Run and Verify the App Child Image

Run the child Docker image using the following command.

docker run -d -p 8080:5000 flask-app:1.0

Now, access it on the browser you can see the page as shown below.

ONBUILD Instruction: Gotchas You Need to Know

Here’s a list of potential gotchas when using the ONBUILD instruction in Docker:

1. ONBUILD instructions only run when building a child image. This can cause unexpected behavior if developers are unaware of the stored instructions in the base image.
2. If the ONBUILD instruction in a base image is modified, it may break existing child images that depend on the previous behavior.
3. ONBUILD applies the same instructions to all child images, which may not be suitable for projects that require different build steps.
4. ONBUILD is great for automating simple, repetitive tasks, but it’s not ideal for complex build processes that require more customization.

Conclusion

To wrap up, we’ve explored how to use ONBUILD and its practical applications.

So, why should you use ONBUILD?

• Consistency: It ensures all similar apps follow the standard build process.
• Efficiency: It reduces repetitive code in child Dockerfiles, making them cleaner and easier to maintain.
• Scalability: It allows you to quickly set up new projects without duplicating build steps.

Now I would like to hear from you!

Have you ever used ONBUILD instruction? what are your experiences?

Comment below!