diff --git a/docs/explanations/advanced.md b/docs/explanations/advanced.md index 02a2d46194..a77c205140 100644 --- a/docs/explanations/advanced.md +++ b/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) diff --git a/docs/explanations/detailed-push-process.md b/docs/explanations/detailed-push-process.md index 93cb0ba4f6..cd5c8d71ae 100644 --- a/docs/explanations/detailed-push-process.md +++ b/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. diff --git a/docs/references/commands/cli/app/epinio_app_push.md b/docs/references/commands/cli/app/epinio_app_push.md index 226eaf9611..77d28e0969 100644 --- a/docs/references/commands/cli/app/epinio_app_push.md +++ b/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 diff --git a/docs/references/customization/staging-scripts.md b/docs/references/customization/staging-scripts.md index ba1b376e4d..98310a883e 100644 --- a/docs/references/customization/staging-scripts.md +++ b/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 diff --git a/docs/references/customization/staging.md b/docs/references/customization/staging.md index 910f9b3633..9214032b11 100644 --- a/docs/references/customization/staging.md +++ b/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). diff --git a/docs/references/manifests.md b/docs/references/manifests.md index 0c712c7c23..90b75dcacb 100644 --- a/docs/references/manifests.md +++ b/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` diff --git a/docs/references/supported_applications.md b/docs/references/supported_applications.md index e4cca9e443..9a27110d91 100644 --- a/docs/references/supported_applications.md +++ b/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. diff --git a/docs/tutorials/custom_builder_go.md b/docs/tutorials/custom_builder_go.md index 4258acc0d3..85cf064e84 100644 --- a/docs/tutorials/custom_builder_go.md +++ b/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.