This documentation explains how to create a custom stack based off of the existing Paketo stacks. Check out the stacks concept page for more information about what a stack is and the Paketo offerings.
It’s recommended to use an existent Paketo stack offering, over creating a custom stack in order to leverage the full range of Paketo security patching and compliance standards.
In some cases, a custom stack image may be useful for users who may need an extra system library or user ID, for example. The Cloud Native Buildpacks project already has documentation for creating a stack from scratch, but for some Paketo users it may be simpler and less error-prone to build upon the stack we already provide. It’s still recommended to read the CNB documentation regardless, because there are a lot of details and explanations there that still apply.
This guide assumes you know the basics of stacks from the stacks concept page.
Dockerfile
and define the base
image as one of the Paketo stacks. For example:
FROM paketobuildpacks:full-cnb as base
There are two different options for each of the three (tiny, base, full) stacks you can use.
-cnb
suffix, which can be used as a base image
without any CNB metadata added at all. Ex. docker.io/paketobuildpacks/run:full
-cnb
suffix at the end.
This will be the stack that contains buildpack specific
metadata
already added, and is based off of the non-CNB stack image. Ex.
docker.io/paketobuildpacks/run:full-cnb
Check out the bionic
and tiny
directories in
github.com/paketo-buildpacks/stacks
repo to view the Dockerfiles we have defined for both the base image and CNB images.
Add your desired custom stack change to the Dockerfile such as labels,
environment variables, and/or packages. There are examples in the CNB
documentation .
Note that the changes need to abide by the CNB spec. For example, setting
the CNB_USER_ID
to root isn’t allowed.
Build the stack image with docker build . -t <stack-name>-<run or build>:<tag> --target <target>
for both the build and run images.
Push the stack images to a registry with docker push
Create a custom builder with the stack you want to use. Check out the builder
documentation for details on builders. This can be
achieved by cloning the builder you want to use, and modifying the
builder.toml
file. For example, if you have built a custom stack based off
of the Paketo Full stack, you will want to add it to the Full
builder builder.toml
file. Modify the bottom [stack]
section to point to the registry location
of the build and run images you have pushed to a registry. The id
should
match the stack ID if you specified one in the Dockerfile, or in the base
image you used. It will be io.buildpacks.stacks.bionic
if your base image
was one of the CNB stack images. This ID implies compatibility with the
official io.buildpacks.stacks.bionic
stack.
Create the builder with the pack CLI.
pack builder create <builder-name> —config <path to builder.toml>
Ensure the buildpacks of interest support the wildcard (“*”) stack or
support the stack ID you provided in the builder.toml
by checking the buildpack stacks
section. For example, the
node-engine
buildpack
only supports stacks with ID io.buildpacks.stacks.bionic
. If you build
upon one of the Paketo -cnb
stacks, your custom stack will be
compatible already, since part of the CNB metadata added is the ID.
Perform builds with the newly created builder image, which uses the custom stack images.
Last modified: May 12, 2022