Create a builder

Creating a custom builder allows you to control what buildpacks are used and what image apps are based on.

As part of this guide we’ll create a basic builder that uses mostly no-op buildpacks to show you around a bit.

0. Grab the sample repo

Before we start, let’s pull down a few buildpacks from our samples repo.

# clone the repo
git clone https://github.com/buildpack/samples

1. Builder configuration

First, let’s create a builder configuration file (builder.toml) with the following contents:

# Buildpacks to include in builder
[[buildpacks]]
uri = "samples/buildpacks/hello-moon"

[[buildpacks]]
uri = "samples/buildpacks/hello-processes"

[[buildpacks]]
uri = "samples/buildpacks/hello-world"

# Order used for detection
[[order]]
    # This buildpack will display build-time information (as a dependency)
    [[order.group]]
    id = "io.buildpacks.samples.hello-world"
    version = "0.0.1"
    
    # This buildpack will display build-time information (as a dependant)
    [[order.group]]
    id = "io.buildpacks.samples.hello-moon"
    version = "0.0.1"
    
    # This buildpack will create a process type "sys-info" to display runtime information
    [[order.group]]
    id = "io.buildpacks.samples.hello-processes"
    version = "0.0.1"

# Stack that will be used by the builder
[stack]
id = "io.buildpacks.samples.stacks.bionic"
# This image is used at runtime
run-image = "cnbs/sample-stack-run:bionic"
# This image is used at build-time
build-image = "cnbs/sample-stack-build:bionic"

2. Create builder

Creating a builder is now as simple as running the following command:

# create builder 
pack create-builder my-builder:bionic --builder-config ./builder.toml

Tip: create-builder has a --publish flag that can be used to publish the generated builder image to a registry.

Congratulations! You’ve got a custom builder.

3. Use your builder

Let’s go a little further and use our builder to build an app by running:

pack build my-app --builder my-builder:bionic --path samples/apps/java-maven/

4. Running the app

Remember that we mentioned that the buildpacks we used as part of this builder don’t really do much. To be honest, they didn’t even use the app source code. What they did do was show the environment in which they run on and now by running the app image with CNB_PROCESS_TYPE=sys-info we can see the runtime information as well.

docker run --rm --env CNB_PROCESS_TYPE=sys-info -it my-app

We’re sure you’ll be able to create more useful builders.

References

For additional sample builders and buildpacks, check out our samples repo.