Working with builders using create-builder

pack create-builder enables buildpack authors and platform operators to bundle a collection of buildpacks into a single image for distribution and use with a specified stack.

$ pack create-builder <image-name> --builder-config <path-to-builder-toml>

Example: Creating a builder from buildpacks

In this example, a builder image is created from buildpacks org.example.buildpack-1 and org.example.buildpack-2. A TOML file (typically named builder.toml) file provides necessary configuration to the command.

[[buildpacks]]
  id = "org.example.buildpack-1"
  uri = "relative/path/to/buildpack-1" # URIs without schemes are read as paths relative to builder.toml

[[buildpacks]]
  id = "org.example.buildpack-2"
  uri = "https://example.org/buildpacks/buildpack-2.tgz"

[[groups]]
  [[groups.buildpacks]]
    id = "org.example.buildpack-1"
    version = "0.0.1"
  
  [[groups.buildpacks]]
    id = "org.example.buildpack-2"
    version = "0.0.1"

[stack]
  id = "com.example.stack"
  build-image = "example/build"
  run-image = "example/run"

For more information on stacks, see the Managing stacks section.

Running create-builder while supplying this configuration file will produce the builder image.

$ pack create-builder my-builder:my-tag --builder-config path/to/builder.toml

2018/10/29 15:35:47 Pulling builder base image packs/build
2018/10/29 15:36:06 Successfully created builder image: my-builder:my-tag

Like build, create-builder has a --publish flag that can be used to publish the generated builder image to a registry.

The builder can then be used in build by running:

$ pack build my-app:my-tag --builder my-builder:my-tag --buildpack org.example.buildpack-1

Builders explained

create-builder diagram

A builder is an image containing a collection of buildpack groups that will be executed against app source code, in the order that they appear in builder.toml. This image’s base will be the build image associated with a given stack.

A buildpack’s primary role is to inspect the source code, determine any dependencies that will be required to compile and/or run the app, and provide runtime dependencies as layers in the final app image.

It’s important to note that the buildpacks in a builder are not actually executed until build is run.


Last modified by Andrew Meyer