Clarify buildpack builder defaults and overrides

docs/explanations/advanced.md

@@ -163,8 +163,7 @@ from the sources to the Epinio server,
 copying into Epinio's internal (or external) S3 storage.
 It's then copied from that storage to a `PersistentVolumeClaim`
 to use in the job for staging.
-Staging is the compilation and creation of the docker image
-for use by the underlying Kubernetes cluster.
+Staging uses a [Cloud Native Buildpacks](https://buildpacks.io/) builder image (default: Paketo full stack) to build the container image for use by the underlying Kubernetes cluster; see the [detailed push process](detailed-push-process.md) and [buildpack customization](references/customization/staging.md).
 
 The process is different when using the Epinio client's "git mode".
 In this mode [`epinio push`](../references/commands/cli/epinio_push.md)

docs/explanations/detailed-push-process.md

@@ -66,9 +66,10 @@ Supported formats are: **zip**, **tar**, **tgz**, **tbz**, and **txz**
 
 ## Stage (step 7)
 
-The third step of staging uses the
-[Paketo buildpacks](https://paketo.io/)
+The third step of staging uses a [Cloud Native Buildpacks](https://buildpacks.io/) builder image
 to create a container image for your application.
+By default Epinio uses the [Paketo full stack builder](https://paketo.io/) (jammy);
+you can use [non-Paketo buildpack builders](../references/customization/staging.md#using-non-paketo-buildpacks) by setting the builder image at install time or per push.
 The result of a successful staging process is a new image.
 This image is pushed to the Registry component of Epinio.
 Read further information in the [Epinio Registry](../explanations/advanced.md#container-registry) documentation.

docs/references/commands/cli/app/epinio_app_push.md

@@ -20,7 +20,7 @@ epinio app push [flags] [PATH_TO_APPLICATION_MANIFEST]
 ```
       --app-chart string             App chart to use for deployment
   -b, --bind strings                 configurations to bind immediately
-      --builder-image string         Paketo builder image to use for staging
+      --builder-image string         Buildpack builder image to use for staging (default: Paketo full stack)
   -v, --chart-value strings          chart customization to be used
   -z, --clear-routes                 clear routes / no routes
       --container-image-url string   Container image url for the app workload image

docs/references/customization/staging-scripts.md

@@ -14,23 +14,19 @@ This customization interacts with the
 [customization of buildpacks](staging.md).
 :::
 
-Epinio uses staging scripts to interact with Paketo [Cloud Native Buildpacks](https://buildpacks.io/).
+Epinio uses staging scripts to run [Cloud Native Buildpacks](https://buildpacks.io/) (e.g. Paketo or other builder images).
 
 Epinio automatically selects the set of staging scripts based on the name of the chosen builder
-image, and the images supported by a specific definition.
+image and the images supported by each script definition.
 
-By default Epinio installs three definitions.
+By default Epinio installs three definitions:
 
-  1. One to support Bionic-based builder images (`paketo-buildpacks/builder:*`).
-  1. One to support Jammy-based  builder images (`paketo-buildpacks/builder-jammy-*:*`).
-  1. One to serve as fallback for any images not captured by the other two.
+  1. One to support Bionic-based Paketo builder images (`paketo-buildpacks/builder:*`).
+  2. One to support Jammy-based Paketo builder images (`paketo-buildpacks/builder-jammy-*:*`).
+  3. One that serves as a fallback for any other builder image (including non-Paketo and custom builders).
 
-It is this last definition which is configured when [customizing buildpacks](staging.md)
-with a different image.
-
-By default this fallback is configured for Jammy-based images in general, and the
-[jammy full stack paketo builder image](https://github.com/paketo-buildpacks/builder-jammy-full)
-in particular
+When you [customize buildpacks](staging.md) to use a different default builder, or push with a non-Paketo builder via `--builder-image`, Epinio uses the fallback definition.
+By default that fallback is tuned for Jammy-based images and the [Paketo jammy full stack builder](https://github.com/paketo-buildpacks/builder-jammy-full).
 
 ## Specification
 

docs/references/customization/staging.md

@@ -9,18 +9,30 @@ keywords: [kubernetes, epinio, application development, buildpacks]
 This customization interacts with the [customization of staging scripts](staging-scripts.md).
 :::
 
-By default, Epinio's staging process uses the [jammy full stack paketo builder image](https://github.com/paketo-buildpacks/builder-jammy-full) for Paketo [Cloud Native Buildpacks](https://buildpacks.io/).
-This converts application sources into deployable application images.
+Epinio uses [Cloud Native Buildpacks](https://buildpacks.io/) to convert application sources into deployable container images.
+By default, staging uses the [Paketo jammy full stack builder image](https://github.com/paketo-buildpacks/builder-jammy-full).
+You can use any compatible buildpack builder image—including non-Paketo and custom builders—by configuring the default builder or overriding it per push.
 
-To use a different builder image set the chart keys
+### Default builder image
+
+To set a different default builder image for the cluster, set these chart keys before installation:
 
 - `image.builder.repository`
 - `image.builder.tag`
 - `image.builder.userid`
 - `image.builder.groupid`
 
-to the desired values before installation.
+### Override per push
+
+To use a different builder image for a single application, use the `--builder-image` option of [epinio push](../commands/cli/epinio_push.md), or set `staging.builder` in your [application manifest](../manifests.md).
+
+### Using non-Paketo buildpacks
+
+Epinio supports any [Cloud Native Buildpack](https://buildpacks.io/) builder image, not only Paketo. For example:
+
+- **Custom builders**: Build your own builder with [`pack`](https://buildpacks.io/docs/tools/pack/) and use it with `--builder-image` or in the manifest. See [Deploying a complex application with a custom builder](../../tutorials/custom_builder_go.md).
+- **Other ecosystems**: Use builder images from other buildpack ecosystems (e.g. Heroku-style or other CNB-compatible builders) by setting the default builder at install time or `--builder-image` / `staging.builder` when pushing.
 
-To override the builder image on an individual basis use the option `--builder-image` of the [epinio push](../commands/cli/epinio_push.md) command.
+The staging job runs the builder image you specify; Epinio selects the appropriate [staging scripts](staging-scripts.md) based on the builder image name (with a fallback for images that do not match Paketo patterns).
 
-Note also the related documentation about the [supported applications](../supported_applications.md).
+See also [supported applications](../supported_applications.md).

docs/references/manifests.md

@@ -33,7 +33,7 @@ Further defaults:
   - No environment variables.
   - No bound configurations.
   - One replica/instance.
-  - Standard paketo builder image (`paketobuildpacks/builder:full`).
+  - Default buildpack builder image (Paketo full stack; [customizable](customization/staging.md)).
   - Current directory for the application sources.
 
 ## Syntax `epinio (apps) push`

docs/references/supported_applications.md

@@ -19,14 +19,18 @@ You can see a simplified diagram of the process in the image below:
 
 ![epinio-push-simplified](epinio-push-simple.svg?raw=true "Epinio push")
 
-After pushing your code, Epinio creates staging job which uses the [paketo buildpacks](https://paketo.io/) to build a runtime image for your application.
-If you are not familiar with how buildpacks work, you should have a look at the official docs: https://buildpacks.io/docs/
+After pushing your code, Epinio creates a staging job that uses a buildpack builder image to build a runtime image.
+By default Epinio uses the [Paketo full builder](https://paketo.io/); you can also use [non-Paketo or custom buildpack builders](customization/staging.md#using-non-paketo-buildpacks).
+If you are not familiar with how buildpacks work, see the official docs: https://buildpacks.io/docs/
 
 ## Supported buildpacks
 
-Epinio uses the [Paketo full builder image](https://github.com/paketo-buildpacks/full-builder) which means you can make use of any of the buildpacks
+Epinio uses a **default** [Paketo full builder image](https://github.com/paketo-buildpacks/builder-jammy-full) (jammy stack), so you can use any of the buildpacks
 documented here: https://paketo.io/docs/concepts/builders/#full
 
+You can override the builder image per push (e.g. `--builder-image`) or set a different default at install time.
+That allows using custom builders or other buildpack ecosystems; see [Buildpacks customization](customization/staging.md).
+
 The various buildpacks provide various configuration options. You can read on how to generally configure a buildpack here: https://paketo.io/docs/buildpacks/configuration/
 Each buildpack may support more configuration options, so you may have to read the documentation of the buildpacks you are interested in.
 

docs/tutorials/custom_builder_go.md

@@ -11,9 +11,10 @@ to work through a more complex application with Epinio.
 
 Gitea is a self-hosted Git service, written in Go and Node.js.
 
+Epinio supports any [Cloud Native Buildpack](https://buildpacks.io/) builder image (default is Paketo; you can use custom or other builders via `--builder-image` or [staging customization](../references/customization/staging.md)).
 At the time of writing the Paketo Go buildpack doesn't support Node.js asset compilation,
 (see [issue #671](https://github.com/paketo-buildpacks/go/issues/671)),
-so you need to create a custom builder.
+so this tutorial uses a custom builder.
 
 The builder checks the needed Go and Node dependencies,
 and executes the `make` command to build both the front end and the back end.