From fa2c7bfefa59a76cc44104f6fd802992056b5443 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Sun, 27 Oct 2024 21:18:38 -0400 Subject: [PATCH 01/12] adds content to 2 app developer pages Signed-off-by: Hanan Younes --- .../concepts/experimental-features.md | 18 ++++++++++++++++++ .../build-outputs/understand-failures.md | 4 ++-- 2 files changed, 20 insertions(+), 2 deletions(-) create mode 100644 content/docs/for-app-developers/concepts/experimental-features.md diff --git a/content/docs/for-app-developers/concepts/experimental-features.md b/content/docs/for-app-developers/concepts/experimental-features.md new file mode 100644 index 000000000..b50c6340c --- /dev/null +++ b/content/docs/for-app-developers/concepts/experimental-features.md @@ -0,0 +1,18 @@ ++++ +title="What are experimental features?" +weight=8 ++++ + +Certain features are considered `experimental` and susceptible to change in a future API version. + + + +This means users will need to enable the `experimental` mode in order to use one of these feature. + +To enable these features, run `pack config experimental true`, or add `experimental = true` to the `~/.pack/config.toml` file. + +For example, exporting your application to disk in `OCI` layout format is an experimental feature available on `pack` since version `v0.30.0` + +For more information and to look at an example of how this might be valuable, see [Export to OCI layout format on disk][exp-feature]. + +[exp-feature]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/export-to-oci-layout/ diff --git a/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md b/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md index 4c35fe79b..e77e17f63 100644 --- a/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md +++ b/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md @@ -4,6 +4,6 @@ weight=99 summary="How to troubleshoot when things go wrong." +++ -This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon. +While `Buildpacks` help developers transform applications' source code into container images that can run on any cloud, creating an error-free experience remains far from achieved. -If you are familiar with this content and would like to make a contribution, please feel free to open a PR :) +This guide explores some of the most common issues that may prevent image build completion and provides troubleshooting tips to help end-users navigate these issues. From e511194e9586c95db3d469b08addf8f675d0822b Mon Sep 17 00:00:00 2001 From: Hanan Younes <56159764+hyounes4560@users.noreply.github.com> Date: Mon, 4 Nov 2024 03:17:35 -0500 Subject: [PATCH 02/12] adds platform environment variables related content from the spec (#771) * adds platform env var related content from the spec Signed-off-by: Hanan Younes --------- Signed-off-by: Hanan Younes --- .../how-to/build-inputs/build-env.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 content/docs/for-platform-operators/how-to/build-inputs/build-env.md diff --git a/content/docs/for-platform-operators/how-to/build-inputs/build-env.md b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md new file mode 100644 index 000000000..7efdc32b7 --- /dev/null +++ b/content/docs/for-platform-operators/how-to/build-inputs/build-env.md @@ -0,0 +1,34 @@ ++++ +title="Specify the build time environment variables" +weight=4 ++++ + +`Environment variables` are used to configure buildpack behavior. They may be specified by: + +* The platform operator (this page) +* The end user (see [Customize buildpack behavior with build-time environment variables][end user]) +* Other buildpacks (see [Specify the environment][env]) + + + +When more than one entity specifies the same `environment variable`, the order of precedence is as shown above, with the platform operator having ultimate say over what the final value of the variable will be. + +The platform operator specifies `environment variables` in a manner that is very similar to buildpacks (see XXX), but with a few differences. Namely: + +* The directory for environment variable settings `/cnb/build-config` +* When no suffix is provided, the modification behavior is `default` +For more information, consult the [Platform Specification](https://github.com/buildpacks/spec/blob/main/platform.md). + +### Example + +Platform operators can make choices that "override" or provide defaults for application authors. In the following configuration the platform operator overrides the value of `CGO_ENABLED` for all application authors. The value of `PIP_VERBOSE` is set by default and can be overridden by buildpack authors or application authors. Any value for the environment variable `CLASSPATH` is prepended with the values provided by the platform operator. + +```bash +$ tree /cnb/buildconfig/env +├── CGO_ENABLED.override +├── PIP_VERBOSE +└── CLASSPATH.prepend +``` + +[env]: https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/specify-env/ +[end user]: https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment/ From de0aeff12c18f4e11d85b3b85f1a5a0103bfe3ae Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 6 Nov 2024 19:49:49 +0000 Subject: [PATCH 03/12] Bump buildpacks/github-actions from 5.7.4 to 5.8.1 (#782) Bumps [buildpacks/github-actions](https://github.com/buildpacks/github-actions) from 5.7.4 to 5.8.1. - [Release notes](https://github.com/buildpacks/github-actions/releases) - [Commits](https://github.com/buildpacks/github-actions/compare/v5.7.4...v5.8.1) --- updated-dependencies: - dependency-name: buildpacks/github-actions dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 6506c2b22..cbf93b47f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -24,7 +24,7 @@ jobs: - name: Install Dependencies run: sudo apt-get install make curl jq - name: Install pack - uses: buildpacks/github-actions/setup-pack@v5.7.4 + uses: buildpacks/github-actions/setup-pack@v5.8.1 with: pack-version: '0.31.0' - name: Test From b172432918e01a2b5316149e9266968709177e05 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 6 Nov 2024 19:51:21 +0000 Subject: [PATCH 04/12] Bump github.com/golang-jwt/jwt/v4 from 4.5.0 to 4.5.1 in /tools (#781) Bumps [github.com/golang-jwt/jwt/v4](https://github.com/golang-jwt/jwt) from 4.5.0 to 4.5.1. - [Release notes](https://github.com/golang-jwt/jwt/releases) - [Changelog](https://github.com/golang-jwt/jwt/blob/main/VERSION_HISTORY.md) - [Commits](https://github.com/golang-jwt/jwt/compare/v4.5.0...v4.5.1) --- updated-dependencies: - dependency-name: github.com/golang-jwt/jwt/v4 dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Aidan Delaney --- tools/go.mod | 2 +- tools/go.sum | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/tools/go.mod b/tools/go.mod index 666f967e1..ef089d0cf 100644 --- a/tools/go.mod +++ b/tools/go.mod @@ -132,7 +132,7 @@ require ( github.com/gohugoio/hugo-goldmark-extensions/passthrough v0.2.0 // indirect github.com/gohugoio/locales v0.14.0 // indirect github.com/gohugoio/localescompressed v1.0.1 // indirect - github.com/golang-jwt/jwt/v4 v4.5.0 // indirect + github.com/golang-jwt/jwt/v4 v4.5.1 // indirect github.com/golang-jwt/jwt/v5 v5.2.1 // indirect github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect github.com/golang/protobuf v1.5.4 // indirect diff --git a/tools/go.sum b/tools/go.sum index a681d2f3e..55ac677e1 100644 --- a/tools/go.sum +++ b/tools/go.sum @@ -378,8 +378,9 @@ github.com/gohugoio/testmodBuilder/mods v0.0.0-20190520184928-c56af20f2e95 h1:sg github.com/gohugoio/testmodBuilder/mods v0.0.0-20190520184928-c56af20f2e95/go.mod h1:bOlVlCa1/RajcHpXkrUXPSHB/Re1UnlXxD1Qp8SKOd8= github.com/golang-jwt/jwt/v4 v4.0.0/go.mod h1:/xlHOz8bRuivTWchD4jCa+NbatV+wEUSzwAxVc6locg= github.com/golang-jwt/jwt/v4 v4.2.0/go.mod h1:/xlHOz8bRuivTWchD4jCa+NbatV+wEUSzwAxVc6locg= -github.com/golang-jwt/jwt/v4 v4.5.0 h1:7cYmW1XlMY7h7ii7UhUyChSgS5wUJEnm9uZVTGqOWzg= github.com/golang-jwt/jwt/v4 v4.5.0/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0= +github.com/golang-jwt/jwt/v4 v4.5.1 h1:JdqV9zKUdtaa9gdPlywC3aeoEsR681PlKC+4F5gQgeo= +github.com/golang-jwt/jwt/v4 v4.5.1/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0= github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk= github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk= github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q= From 183a23f483dd96fae0f3bde02febbbfb792e7859 Mon Sep 17 00:00:00 2001 From: Aidan Delaney Date: Wed, 6 Nov 2024 20:06:16 +0000 Subject: [PATCH 05/12] Use latest samples image (#779) Bump all examples to use the latest samples based on the latest Ubuntu LTS. Signed-off-by: Aidan Delaney --- content/docs/app-journey.md | 2 +- .../for-app-developers/concepts/builder.md | 2 +- .../configure-build-time-environment.md | 6 +++--- .../how-to/build-inputs/use-cache-image.md | 8 ++++---- .../how-to/build-inputs/use-project-toml.md | 8 ++++---- .../how-to/build-inputs/use-volume-mounts.md | 2 +- .../how-to/build-outputs/inspect-app.md | 2 +- .../how-to/special-cases/build-on-podman.md | 2 +- .../special-cases/export-to-oci-layout.md | 4 ++-- .../how-to/special-cases/use-http-proxy.md | 6 +++--- .../tutorials/basic-app/_index.md | 6 +++--- .../how-to/write-buildpacks/get-started.md | 2 +- .../01_setup-local-environment.md | 2 +- .../basic-buildpack/02_building-blocks-cnb.md | 10 +++++----- .../build-inputs/create-builder/build-base.md | 6 +++--- .../build-inputs/create-builder/builder.md | 18 +++++++++--------- .../build-inputs/create-builder/run-base.md | 6 +++--- .../how-to/build-inputs/stack.md | 12 ++++++------ .../tutorials/lifecycle/_index.md | 12 ++++++------ .../static/images/pack-hello-world-nodejs.cast | 6 +++--- 20 files changed, 61 insertions(+), 61 deletions(-) diff --git a/content/docs/app-journey.md b/content/docs/app-journey.md index 62f486145..90c220ee3 100644 --- a/content/docs/app-journey.md +++ b/content/docs/app-journey.md @@ -63,7 +63,7 @@ cd samples/apps/java-maven 3. Build the app using [`pack`][pack-docs] ``` -pack build myapp --builder cnbs/sample-builder:jammy +pack build myapp --builder cnbs/sample-builder:noble ``` diff --git a/content/docs/for-app-developers/concepts/builder.md b/content/docs/for-app-developers/concepts/builder.md index b583e06f1..557311492 100644 --- a/content/docs/for-app-developers/concepts/builder.md +++ b/content/docs/for-app-developers/concepts/builder.md @@ -10,7 +10,7 @@ a [build-time base image], a [lifecycle] binary, and a reference to a [runtime b The [build-time base image] provides the base environment for the `builder` -(e.g., an Ubuntu Jammy OS image with build tooling) and +(e.g., an Ubuntu Noble OS image with build tooling) and a [runtime base image] provides the base environment for the `app image` during runtime. ![builder](/images/builder.svg) diff --git a/content/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md b/content/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md index 817725886..227ffe282 100644 --- a/content/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md +++ b/content/docs/for-app-developers/how-to/build-inputs/configure-build-time-environment.md @@ -33,7 +33,7 @@ export FOO=BAR pack build sample-app \ --env "HELLO=WORLD" \ --env "FOO" \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --buildpack samples/buildpacks/hello-world/ \ --buildpack samples/apps/bash-script/bash-script-buildpack/ \ --path samples/apps/bash-script/ @@ -79,7 +79,7 @@ echo -en "HELLO=WORLD\nFOO" > ./envfile ``` pack build sample-app \ --env-file ./envfile \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --buildpack samples/buildpacks/hello-world/ \ --buildpack samples/apps/bash-script/bash-script-buildpack/ \ --path samples/apps/bash-script/ @@ -125,7 +125,7 @@ EOL 2. Build the app ``` pack build sample-app \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --buildpack samples/buildpacks/hello-world/ \ --buildpack samples/apps/bash-script/bash-script-buildpack/ \ --path samples/apps/bash-script/ diff --git a/content/docs/for-app-developers/how-to/build-inputs/use-cache-image.md b/content/docs/for-app-developers/how-to/build-inputs/use-cache-image.md index b11c61779..a7a041b35 100644 --- a/content/docs/for-app-developers/how-to/build-inputs/use-cache-image.md +++ b/content/docs/for-app-developers/how-to/build-inputs/use-cache-image.md @@ -29,10 +29,10 @@ For the following examples we will use: > **NOTE:** If we wish to publish to an external registry like `Dockerhub` we will first need to authenticate with `docker` to allow us to push images. We can do this via `docker login` -Next we trust the `cnbs/sample-builder:jammy` builder in order to allow access to docker credentials when publishing. +Next we trust the `cnbs/sample-builder:noble` builder in order to allow access to docker credentials when publishing. ``` -pack config trusted-builders add cnbs/sample-builder:jammy +pack config trusted-builders add cnbs/sample-builder:noble ``` @@ -42,7 +42,7 @@ To build the `localhost:5000/buildpack-examples/cache-image-example` application ``` pack build localhost:5000/buildpack-examples/cache-image-example \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --buildpack samples/java-maven \ --path samples/apps/java-maven \ --cache-image localhost:5000/buildpack-examples/maven-cache-image:latest \ @@ -76,7 +76,7 @@ builds may also update the specified `cache-image`. The following command will restore data for the `samples/java-maven:maven_m2` layer from the cache image. ``` pack build localhost:5000/buildpack-examples/second-cache-image-example \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --buildpack samples/java-maven \ --path samples/apps/java-maven \ --cache-image localhost:5000/buildpack-examples/maven-cache-image:latest \ diff --git a/content/docs/for-app-developers/how-to/build-inputs/use-project-toml.md b/content/docs/for-app-developers/how-to/build-inputs/use-project-toml.md index 91920c924..c9505c425 100644 --- a/content/docs/for-app-developers/how-to/build-inputs/use-project-toml.md +++ b/content/docs/for-app-developers/how-to/build-inputs/use-project-toml.md @@ -45,7 +45,7 @@ To use a `project.toml` file, simply: ```shell script # build the app pack build sample-app \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --path samples/apps/bash-script/ # run the app @@ -55,7 +55,7 @@ docker run sample-app If the descriptor is named `project.toml`, it will be read by `pack` automatically. Otherwise, you can run: ```shell script pack build sample-app \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --path samples/apps/bash-script/ \ --descriptor samples/apps/bash-script/ ``` @@ -99,7 +99,7 @@ Paste the above `toml` as `new-project.toml` in the `samples/apps/bash-script/` ```shell script # build the app pack build sample-app \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --path samples/apps/bash-script/ \ --descriptor samples/apps/bash-script/new-project.toml @@ -112,7 +112,7 @@ The builder can also be [specified](https://github.com/buildpacks/spec/blob/main ```toml [io.buildpacks] -builder = "cnbs/sample-builder:jammy" +builder = "cnbs/sample-builder:noble" ``` ```shell script diff --git a/content/docs/for-app-developers/how-to/build-inputs/use-volume-mounts.md b/content/docs/for-app-developers/how-to/build-inputs/use-volume-mounts.md index e5dc705f7..7e55bbe4f 100644 --- a/content/docs/for-app-developers/how-to/build-inputs/use-volume-mounts.md +++ b/content/docs/for-app-developers/how-to/build-inputs/use-volume-mounts.md @@ -83,7 +83,7 @@ Now, we can mount this volume during `pack build`: ```bash ls -al pack build volume-example \ - --builder cnbs/sample-builder:jammy \ + --builder cnbs/sample-builder:noble \ --buildpack samples/buildpacks/hello-world \ --path samples/apps/bash-script \ --volume test-volume:/platform/volume:ro diff --git a/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md b/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md index 3d97b4288..b09364ce9 100644 --- a/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md +++ b/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md @@ -21,7 +21,7 @@ You should see the following: ```text Run Images: - cnbs/sample-base-run:jammy + cnbs/sample-base-run:noble ... Buildpacks: diff --git a/content/docs/for-app-developers/how-to/special-cases/build-on-podman.md b/content/docs/for-app-developers/how-to/special-cases/build-on-podman.md index 6f0d16c32..6650c7370 100644 --- a/content/docs/for-app-developers/how-to/special-cases/build-on-podman.md +++ b/content/docs/for-app-developers/how-to/special-cases/build-on-podman.md @@ -49,7 +49,7 @@ git clone https://github.com/buildpacks/samples ![](https://i.imgur.com/0mmV6K7.png) ```shell=bash -pack build sample-app -p samples/apps/ruby-bundler/ -B cnbs/sample-builder:jammy +pack build sample-app -p samples/apps/ruby-bundler/ -B cnbs/sample-builder:noble ``` Where: diff --git a/content/docs/for-app-developers/how-to/special-cases/export-to-oci-layout.md b/content/docs/for-app-developers/how-to/special-cases/export-to-oci-layout.md index 9cb16d027..71fd59fe0 100644 --- a/content/docs/for-app-developers/how-to/special-cases/export-to-oci-layout.md +++ b/content/docs/for-app-developers/how-to/special-cases/export-to-oci-layout.md @@ -51,7 +51,7 @@ The OCI layout feature must be enabled using the convention `oci: -For this guide we're actually going to use a sample builder, `cnbs/sample-builder:jammy`, which is not listed +For this guide we're actually going to use a sample builder, `cnbs/sample-builder:noble`, which is not listed as a suggested builder for good reason. It's a sample. ### 2. Build your app @@ -41,12 +41,12 @@ ls samples || git clone https://github.com/buildpacks/samples 2. Build the app ``` -pack build sample-app --path samples/apps/java-maven --builder cnbs/sample-builder:jammy +pack build sample-app --path samples/apps/java-maven --builder cnbs/sample-builder:noble ``` > **TIP:** If you don't want to keep specifying a builder every time you build, you can set it as your default -> builder by running `pack config default-builder ` for example `pack config default-builder cnbs/sample-builder:jammy` +> builder by running `pack config default-builder ` for example `pack config default-builder cnbs/sample-builder:noble` ### 3. Run it diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/get-started.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/get-started.md index 771a5568a..33153eba4 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/get-started.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/get-started.md @@ -37,7 +37,7 @@ os = "linux" # Stacks (deprecated) the buildpack will work with [[stacks]] -id = "io.buildpacks.stacks.jammy" +id = "io.buildpacks.stacks.noble" ``` For more information, see [buildpack config](/docs/reference/config/buildpack-config). diff --git a/content/docs/for-buildpack-authors/tutorials/basic-buildpack/01_setup-local-environment.md b/content/docs/for-buildpack-authors/tutorials/basic-buildpack/01_setup-local-environment.md index e273239d1..c9f673120 100644 --- a/content/docs/for-buildpack-authors/tutorials/basic-buildpack/01_setup-local-environment.md +++ b/content/docs/for-buildpack-authors/tutorials/basic-buildpack/01_setup-local-environment.md @@ -20,7 +20,7 @@ Before we get started, make sure you've got the following installed: diff --git a/content/docs/for-buildpack-authors/tutorials/basic-buildpack/02_building-blocks-cnb.md b/content/docs/for-buildpack-authors/tutorials/basic-buildpack/02_building-blocks-cnb.md index 51642db88..739ed387a 100644 --- a/content/docs/for-buildpack-authors/tutorials/basic-buildpack/02_building-blocks-cnb.md +++ b/content/docs/for-buildpack-authors/tutorials/basic-buildpack/02_building-blocks-cnb.md @@ -25,7 +25,7 @@ pack buildpack new examples/node-js \ --api 0.10 \ --path node-js-buildpack \ --version 0.0.1 \ - --stacks io.buildpacks.samples.stacks.jammy + --stacks io.buildpacks.samples.stacks.noble ``` This command will create `node-js-buildpack` directory which contains `buildpack.toml`, `bin/build`, `bin/detect` files. @@ -58,13 +58,13 @@ os = "linux" # Stacks (deprecated) the buildpack will work with [[stacks]] - id = "io.buildpacks.samples.stacks.jammy" + id = "io.buildpacks.samples.stacks.noble" ``` The buildpack ID is the way you will reference the buildpack when you create buildpack groups, builders, etc. [Targets](/docs/for-buildpack-authors/concepts/targets/) identifies the kind of build and run base images the buildpack will work with. -The stack ID (deprecated) uniquely identifies a build and run image configuration the buildpack will work with. This example can be run on Ubuntu Jammy. +The stack ID (deprecated) uniquely identifies a build and run image configuration the buildpack will work with. This example can be run on Ubuntu Noble. ### `detect` and `build` @@ -102,7 +102,7 @@ Set your default [builder][builder] by running the following: ```bash -pack config default-builder cnbs/sample-builder:jammy +pack config default-builder cnbs/sample-builder:noble ``` @@ -110,7 +110,7 @@ Tell pack to trust our default builder: ```bash -pack config trusted-builders add cnbs/sample-builder:jammy +pack config trusted-builders add cnbs/sample-builder:noble ``` diff --git a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base.md index 3edce4a4c..42950c201 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base.md @@ -17,7 +17,7 @@ We need a Dockerfile similar to the following: ```Dockerfile # Define the base image -FROM ubuntu:jammy +FROM ubuntu:noble # Install packages that we want to make available at build time RUN apt-get update && \ @@ -44,7 +44,7 @@ LABEL io.buildpacks.base.distro.version="your distro version" ### Define the base image -We start with `ubuntu:jammy` as our base image. +We start with `ubuntu:noble` as our base image. You can use any operating system, operating system distribution, and operating system distribution version of your choosing, as long as they are supported by the available buildpacks. @@ -71,5 +71,5 @@ To determine which values to provide, see [targets](/docs/for-buildpack-authors/ ## Build the build base image ```bash -docker build . -t cnbs/sample-base-build:jammy +docker build . -t cnbs/sample-base-build:noble ``` diff --git a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/builder.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/builder.md index 8be4d64dd..868efd7c0 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/builder.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/builder.md @@ -55,20 +55,20 @@ uri = "docker://cnbs/sample-package:hello-universe" # Base images used to create the builder [build] -image = "cnbs/sample-base-build:jammy" +image = "cnbs/sample-base-build:noble" [run] [[run.images]] -image = "cnbs/sample-base-run:jammy" -mirrors = ["other-registry.example.com/cnbs/sample-base-run:jammy"] +image = "cnbs/sample-base-run:noble" +mirrors = ["other-registry.example.com/cnbs/sample-base-run:noble"] # Stack (deprecated) used to create the builder [stack] -id = "io.buildpacks.samples.stacks.jammy" +id = "io.buildpacks.samples.stacks.noble" # This image is used at runtime -run-image = "cnbs/sample-base-run:jammy" -run-image-mirrors = ["other-registry.example.com/cnbs/sample-base-run:jammy"] +run-image = "cnbs/sample-base-run:noble" +run-image-mirrors = ["other-registry.example.com/cnbs/sample-base-run:noble"] # This image is used at build-time -build-image = "cnbs/sample-base-build:jammy" +build-image = "cnbs/sample-base-build:noble" ``` ### 2. Create builder @@ -77,7 +77,7 @@ Creating a builder is now as simple as running the following command: ```bash # create builder -pack builder create my-builder:jammy --config ./builder.toml +pack builder create my-builder:noble --config ./builder.toml ``` > **TIP:** `builder create` has a `--publish` flag that can be used to publish the generated builder image to a registry. @@ -89,7 +89,7 @@ pack builder create my-builder:jammy --config ./builder.toml Let's go a little further and use our builder to [`build`][build] an app by running: ```bash -pack build my-app --builder my-builder:jammy --path samples/apps/java-maven/ +pack build my-app --builder my-builder:noble --path samples/apps/java-maven/ ``` ### 4. Running the app diff --git a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base.md index 4d5d3788d..1e6746108 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base.md @@ -17,7 +17,7 @@ We need a Dockerfile similar to the following: ```Dockerfile # Define the base image -FROM ubuntu:jammy +FROM ubuntu:noble # Install packages that we want to make available at run time RUN apt-get update && \ @@ -40,7 +40,7 @@ LABEL io.buildpacks.base.distro.version="your distro version" ### Define the base image -We start with `ubuntu:jammy` as our base image. +We start with `ubuntu:noble` as our base image. You can use any operating system, operating system distribution, and operating system distribution version of your choosing, as long as your application will run there. @@ -62,5 +62,5 @@ To determine which values to provide, see [targets](/docs/for-buildpack-authors/ ## Build the run base image ```bash -docker build . -t cnbs/sample-base-run:jammy +docker build . -t cnbs/sample-base-run:noble ``` diff --git a/content/docs/for-platform-operators/how-to/build-inputs/stack.md b/content/docs/for-platform-operators/how-to/build-inputs/stack.md index 66c505e2d..da2f0c66b 100644 --- a/content/docs/for-platform-operators/how-to/build-inputs/stack.md +++ b/content/docs/for-platform-operators/how-to/build-inputs/stack.md @@ -30,7 +30,7 @@ Before we get started, make sure you've got the following installed: ## Creating a custom stack -We will create a sample stack based on `Ubuntu Jammy Jellyfish`. To create a custom stack, we need to create customized build and run images. +We will create a sample stack based on `Ubuntu Noble Jellyfish`. To create a custom stack, we need to create customized build and run images. To find out how, see [create a build base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base/), then come back here. ## Choose your stack ID @@ -41,10 +41,10 @@ Choose a stack ID to uniquely identify your stack. The stack ID: * should use reverse domain notation to avoid name collisions - i.e. buildpacks.io will be io.buildpacks. Example stack IDs: - * `io.buildpacks.stacks.bionic` - * `io.buildpacks.stacks.jammy` - * `io.buildpacks.samples.stacks.bionic` - * `io.buildpacks.samples.stacks.jammy` + * `io.buildpacks.stacks.noble` + * `io.buildpacks.stacks.noble` + * `io.buildpacks.samples.stacks.noble` + * `io.buildpacks.samples.stacks.noble` ## Label your images @@ -117,7 +117,7 @@ When validating whether the buildpack's mixins are satisfied by a stack, the fol ```toml [[stacks]] -id = "io.buildpacks.stacks.jammy" +id = "io.buildpacks.stacks.noble" mixins = ["build:git", "run:imagemagick", "wget"] ``` diff --git a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md index 0a09a2d74..a80a3e349 100644 --- a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md +++ b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md @@ -105,7 +105,7 @@ cp -r "${CNB_SAMPLES_PATH}/apps/bash-script" ./apps/ Now, you can invoke the `analyzer` for `AMD64` architecture ```text -${CNB_LIFECYCLE_PATH}/analyzer -log-level debug -daemon -layers="./layers" -run-image cnbs/sample-stack-run:jammy apps/bash-script +${CNB_LIFECYCLE_PATH}/analyzer -log-level debug -daemon -layers="./layers" -run-image cnbs/sample-stack-run:noble apps/bash-script ``` Or if you are on an `ARM64` platform @@ -131,17 +131,17 @@ Now the `analyzer`: In this tutorial, there is no previous `apps/bash-script` image, and the output produced should be similar to the following: ```text -sample-stack-run:jammy apps/bash-script +sample-stack-run:noble apps/bash-script Starting analyzer... Parsing inputs... Ensuring privileges... Executing command... Timer: Analyzer started at 2024-09-30T07:38:14Z Image with name "apps/bash-script" not found -Image with name "cnbs/sample-stack-run:jammy" not found +Image with name "cnbs/sample-stack-run:noble" not found Timer: Analyzer ran for 41.92µs and ended at 2024-09-30T07:38:14Z Run image info in analyzed metadata is: -{"Reference":"","Image":"cnbs/sample-stack-run:jammy","Extend":false,"target":{"os":"linux","arch":"amd64"}} +{"Reference":"","Image":"cnbs/sample-stack-run:noble","Extend":false,"target":{"os":"linux","arch":"amd64"}} ``` Now if you `cat ./layers/analyzed.toml`, you should see a few null entries, a `run-image` section that records the provided name provided, and the found `os/arch`. @@ -151,7 +151,7 @@ Now if you `cat ./layers/analyzed.toml`, you should see a few null entries, a `r In this phase, the `detector` looks for an ordered group of buildpacks that will be used during the `build` phase. The `detector` requires an `order.toml` file to be provided. We can derive an order from `builder.toml` in the `samples` directory while removing the deprecated `stack` section as follows: ```text -cat "${CNB_SAMPLES_PATH}/builders/jammy/builder.toml" | grep -v -i "stack" | sed 's/\.\.\/\.\./\./' > order.toml +cat "${CNB_SAMPLES_PATH}/builders/noble/builder.toml" | grep -v -i "stack" | sed 's/\.\.\/\.\./\./' > order.toml ``` @@ -252,7 +252,7 @@ Ensuring privileges... Executing command... No run metadata found at path "/cnb/run.toml" Run image info in analyzed metadata is: -{"Reference":"","Image":"cnbs/sample-stack-run:jammy","Extend":false,"target":{"os":"linux","arch":"amd64"}} +{"Reference":"","Image":"cnbs/sample-stack-run:noble","Extend":false,"target":{"os":"linux","arch":"amd64"}} Timer: Restorer started at 2024-10-01T07:03:47Z Restoring Layer Metadata Reading buildpack directory: /tmp/example/layers/samples_hello-world diff --git a/themes/buildpacks/static/images/pack-hello-world-nodejs.cast b/themes/buildpacks/static/images/pack-hello-world-nodejs.cast index 8c982c9c6..453c3bb92 100644 --- a/themes/buildpacks/static/images/pack-hello-world-nodejs.cast +++ b/themes/buildpacks/static/images/pack-hello-world-nodejs.cast @@ -53,9 +53,9 @@ [5.185983, "o", "Pulling image \u001b[94mregistry.fake/builders/base-builder:latest\u001b[0m\r\n"] [7.002825, "o", "latest: Pulling from /builders/base-builder\r\n"] [7.005319, "o", "Digest: sha256:0a4215114255912cd44f4d353d71b6ac9d000c4aa7d0ac2fecad32d50005c6e6\r\nStatus: Image is up to date for registry.fake/builders/base-builder:latest\r\n"] -[7.03105, "o", "Selected run image \u001b[94mcnbs/sample-stack-run:bionic\u001b[0m\r\nPulling image \u001b[94mcnbs/sample-stack-run:bionic\u001b[0m\r\n"] +[7.03105, "o", "Selected run image \u001b[94mcnbs/sample-stack-run:noble\u001b[0m\r\nPulling image \u001b[94mcnbs/sample-stack-run:noble\u001b[0m\r\n"] [8.424753, "o", "rhel7.101: Pulling from cnbs/sample-stack-run\r\n"] -[8.429182, "o", "Digest: sha256:c595029e3a1af0d2eaa722a584b85b009de10e3ea37f382e74c03d0701976123\r\nStatus: Image is up to date for cnbs/sample-stack-run:bionic\r\n"] +[8.429182, "o", "Digest: sha256:c595029e3a1af0d2eaa722a584b85b009de10e3ea37f382e74c03d0701976123\r\nStatus: Image is up to date for cnbs/sample-stack-run:noble\r\n"] [8.444506, "o", "Downloading buildpack from image: \u001b[94mregistry.fake/buildpacks/nodejs:latest\u001b[0m\r\nPulling image \u001b[94mregistry.fake/buildpacks/nodejs:latest\u001b[0m\r\n"] [9.899592, "o", "latest: "] [9.900318, "o", "Pulling from buildpacks/nodejs\r\n"] @@ -65,7 +65,7 @@ [11.83871, "o", "Adding buildpack \u001b[94mexample/yarn-install@0.0.2\u001b[0m (diffID=sha256:f57bf53c89612c3311160c3ee3269ae2722bf0458e5d931e74753b42e329471d)\r\nAdding buildpack \u001b[94mexample/yarn-start@0.0.3\u001b[0m (diffID=sha256:427c75273cda4a0c50dc6390361aaecd05adf348271ad904d5f7f357ae9bab20)\r\nAdding buildpack \u001b[94mexample/node-engine@0.0.5\u001b[0m (diffID=sha256:89fdef43b493b54a30a2dabd64ff020e11bc96dad55019a22f62975a0be57bdb)\r\nAdding buildpack \u001b[94mexample/npm-install@0.0.2\u001b[0m (diffID=sha256:22f7a9932deefd2182498b844c226f0265af561e61ecf435c1496b61e675842e)\r\nAdding buildpack \u001b[94mexample/npm-start@0.0.2\u001b[0m (diffID=sha256:e3c9a25efa16ace06627a5921a98a2fe6df2090f225542ad20ef71472aa3353d)\r\nAdding buildpack \u001b[94mexample/procfile@0.0.2\u001b[0m (diffID=sha256:6587ae66d2844fb9c1deb10fbb030f66236c2026a723be71aa2673b35aff344e)\r\n"] [11.838805, "o", "Adding buildpack \u001b[94mexample/nodejs@0.0.4\u001b[0m (diffID=sha256:664944158a8294271850e50f6b6a5e175c70620f3e8c1faa9d7a4f5b12b23ca5)\r\nAdding buildpack \u001b[94mexample/yarn@0.0.3\u001b[0m (diffID=sha256:18d9fcfcbd3ddc5c091c4dc7c0920840db9c64d3a68b7c153f43fb01746e598f)\r\n"] [14.283132, "o", "Using build cache volume \u001b[94mpack-cache-library_example_latest-f7816b8f3425.build\u001b[0m\r\nRunning the \u001b[94mcreator\u001b[0m on OS \u001b[94mlinux\u001b[0m with:\r\nContainer Settings:\r\n"] -[14.283284, "o", " Args: \u001b[94m/cnb/lifecycle/creator -daemon -launch-cache /launch-cache -log-level debug -app /workspace -cache-dir /cache -run-image cnbs/sample-stack-run:bionic example\u001b[0m\r\n System Envs: \u001b[94mCNB_PLATFORM_API=0.8\u001b[0m\r\n Image: \u001b[94mpack.local/builder/796d69686a7168636a6a:latest\u001b[0m\r\n User: \u001b[94mroot\u001b[0m\r\n Labels: \u001b[94mmap[author:pack]\u001b[0m\r\nHost Settings:\r\n Binds: \u001b[94mpack-cache-library_example_latest-f7816b8f3425.build:/cache /var/run/docker.sock:/var/run/docker.sock pack-cache-library_example_latest-f7816b8f3425.launch:/launch-cache pack-layers-ardrxkmcst:/layers pack-app-ewomqovqzg:/workspace\u001b[0m\r\n Network Mode: \u001b[94m\u001b[0m\r\n"] +[14.283284, "o", " Args: \u001b[94m/cnb/lifecycle/creator -daemon -launch-cache /launch-cache -log-level debug -app /workspace -cache-dir /cache -run-image cnbs/sample-stack-run:noble example\u001b[0m\r\n System Envs: \u001b[94mCNB_PLATFORM_API=0.8\u001b[0m\r\n Image: \u001b[94mpack.local/builder/796d69686a7168636a6a:latest\u001b[0m\r\n User: \u001b[94mroot\u001b[0m\r\n Labels: \u001b[94mmap[author:pack]\u001b[0m\r\nHost Settings:\r\n Binds: \u001b[94mpack-cache-library_example_latest-f7816b8f3425.build:/cache /var/run/docker.sock:/var/run/docker.sock pack-cache-library_example_latest-f7816b8f3425.launch:/launch-cache pack-layers-ardrxkmcst:/layers pack-app-ewomqovqzg:/workspace\u001b[0m\r\n Network Mode: \u001b[94m\u001b[0m\r\n"] [14.77181, "o", "\u001b[36m===> ANALYZING\u001b[0m\r\n"] [14.8345, "o", "Analyzing image \"d3bd4a0b0f104223fdfeff82ed35701bda03507e2f344c946717a460a74b7227\"\r\n"] [14.835838, "o", "Analyzing image \"98070ee549c522cbc08d15683d134aa0af1817fcdc56f450b07e6b4a7903f9b0\"\r\n"] From f714d5e0170442df374655c4e78732f21e940b9f Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Sat, 9 Nov 2024 17:35:17 -0500 Subject: [PATCH 06/12] adds dive and layers content Signed-off-by: Hanan Younes --- .../docs/for-app-developers/concepts/build.md | 1 - .../how-to/build-outputs/inspect-app.md | 25 +++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/content/docs/for-app-developers/concepts/build.md b/content/docs/for-app-developers/concepts/build.md index 5cafcdf9e..f43baea68 100644 --- a/content/docs/for-app-developers/concepts/build.md +++ b/content/docs/for-app-developers/concepts/build.md @@ -23,5 +23,4 @@ Builders provide a convenient way to distribute buildpacks. [build-time base image]: /docs/for-app-developers/concepts/base-images/build/ [builder]: /docs/for-platform-operators/concepts/builder [buildpack]: /docs/for-app-developers/concepts/buildpack/ -[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/ [runtime base image]: /docs/for-app-developers/concepts/base-images/run/ diff --git a/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md b/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md index 3d97b4288..165d940f0 100644 --- a/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md +++ b/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md @@ -8,15 +8,19 @@ Buildpacks-built images contain metadata that allow you to audit both the image Information includes: + * The process types that are available and the commands associated with them * The run-image the app image was based on * The buildpacks were used to create the app image * Whether the run-image can be rebased with a new version through the `Rebasable` label or not * And more...! +`Pack` offers a built-in command to help you inspect the resultant image and view some of its contents as shown below: + ```bash pack inspect-image test-node-js-app ``` + You should see the following: ```text @@ -35,4 +39,25 @@ Processes: Apart from the above standard metadata, buildpacks can also populate information about the dependencies they have provided in form of a `Software Bill-of-Materials` or [SBOM]. +As already mentioned, buildpacks help you get an `OCI` images that are constructed in a way that’s easy to understand and update with each of the layers being meaningful and independent of all other layers. You can get more details about each layer and how it was created to better understand how the [Build] actually worked. + +There are some available tools that help you achieve this and understand what is contained in your `OCI` image; a popular one is [Dive]. + +Dive can help you inspect `OCI` images, view their layers and each layer's details. If you were to build an `OCI` image following the [multi process app] example and run `Dive` on the generated image, you'll be presented with some detailed information about all of the image layers and understand what is in each layer. + +You can use `Dive` as follows: + +```bash +dive multi-process-app +``` + +The output should look similar to the following: + +PLACEHOLDER + +As seen in the output above, you're presented with `Layers`, `Layer Details`, `Image Details`, and `Current Layer Contents`. To view the contents or explore the file tree of any layer, you need to select the layer on the left using the arrow keys. + [SBOM]: /docs/for-app-developers/how-to/build-outputs/download-sbom +[build]: https://buildpacks.io/docs/for-app-developers/concepts/build/ +[Dive]: https://github.com/wagoodman/dive +[multi process app]: https://buildpacks.io/docs/for-app-developers/how-to/build-outputs/specify-launch-process/#build-a-multi-process-app From 4178e77faca941836a84af44005cf80be20a5e91 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Tue, 12 Nov 2024 08:54:03 -0500 Subject: [PATCH 07/12] adds exp. features list Signed-off-by: Hanan Younes --- .../concepts/experimental-features.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/content/docs/for-app-developers/concepts/experimental-features.md b/content/docs/for-app-developers/concepts/experimental-features.md index b50c6340c..a73274c64 100644 --- a/content/docs/for-app-developers/concepts/experimental-features.md +++ b/content/docs/for-app-developers/concepts/experimental-features.md @@ -7,11 +7,20 @@ Certain features are considered `experimental` and susceptible to change in a fu -This means users will need to enable the `experimental` mode in order to use one of these feature. +This means users will need to enable the `experimental` mode in order to use one of these features. To enable these features, run `pack config experimental true`, or add `experimental = true` to the `~/.pack/config.toml` file. -For example, exporting your application to disk in `OCI` layout format is an experimental feature available on `pack` since version `v0.30.0` +For example, exporting your application to disk in `OCI` layout format is an experimental feature available on `pack` since version `v0.30.0`. + +The following is a list of experimental features: + +* Image extensions +* Windows extensions +* Windows containers +* Windows buildpackage +* Buildpack registry +* Flattening a buildpack package For more information and to look at an example of how this might be valuable, see [Export to OCI layout format on disk][exp-feature]. From accf3fdd3ff848457370a9200627155ff35fe94d Mon Sep 17 00:00:00 2001 From: Robert Gogolok Date: Wed, 13 Nov 2024 23:58:36 +0100 Subject: [PATCH 08/12] Close fenced code block Signed-off-by: Robert Gogolok --- .../docs/for-platform-operators/tutorials/lifecycle/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md index a80a3e349..e1c728936 100644 --- a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md +++ b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md @@ -175,6 +175,7 @@ Before running the `detector`, you need to: ```command $ go install github.com/tomwright/dasel/v2/cmd/dasel@master + ``` Let’s do that for every buildpack in the `samples/buildpacks` directory: From ea3553afadac2a71d9ce42307415e4c1d953a6a7 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 13 Nov 2024 18:50:27 -0500 Subject: [PATCH 09/12] adds reviewers feedback Signed-off-by: Hanan Younes --- .../concepts/experimental-features.md | 33 ++++++++++++------- .../specify-default-launch-process.md | 14 +++----- .../how-to/build-outputs/inspect-app.md | 10 +++--- .../build-outputs/specify-launch-process.md | 2 +- .../build-outputs/understand-failures.md | 33 +++++++++++++++++-- 5 files changed, 63 insertions(+), 29 deletions(-) diff --git a/content/docs/for-app-developers/concepts/experimental-features.md b/content/docs/for-app-developers/concepts/experimental-features.md index a73274c64..a989a05e5 100644 --- a/content/docs/for-app-developers/concepts/experimental-features.md +++ b/content/docs/for-app-developers/concepts/experimental-features.md @@ -3,25 +3,34 @@ title="What are experimental features?" weight=8 +++ -Certain features are considered `experimental` and susceptible to change in a future API version. +Certain features are considered `experimental` and susceptible to change in future API versions. This means users will need to enable the `experimental` mode in order to use one of these features. -To enable these features, run `pack config experimental true`, or add `experimental = true` to the `~/.pack/config.toml` file. +If using `pack`, run `pack config experimental true`, or add `experimental = true` to your `~/.pack/config.toml` file to enable experimental features. -For example, exporting your application to disk in `OCI` layout format is an experimental feature available on `pack` since version `v0.30.0`. +If using the `lifecycle` directly, set the `CNB_EXPERIMENTAL_MODE` [environment variable](https://github.com/buildpacks/spec/blob/main/platform.md#experimental-features). -The following is a list of experimental features: +The following features are experimental for `pack`: -* Image extensions -* Windows extensions -* Windows containers -* Windows buildpackage -* Buildpack registry -* Flattening a buildpack package +* building for [Windows containers][windows] +* exporting to [OCI layout][oci-layout] format on disk +* Interacting with the [buildpack registry][registry] +* `pack manifest` commands +* `pack buildpack --flatten` +* `pack build --interactive` +* When building, reading project metadata version & source URL from [project.toml][project-descriptor] -For more information and to look at an example of how this might be valuable, see [Export to OCI layout format on disk][exp-feature]. +The following features are experimental for `lifecycle`: -[exp-feature]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/export-to-oci-layout/ +* Building for [Windows containers][windows] +* Exporting to [OCI layout][oci-layout] format on disk + +For more information and to look at an example of how this might be valuable, see [Export to OCI layout format on disk][oci-layout]. + +[oci-layout]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/export-to-oci-layout/ +[project-descriptor]: https://buildpacks.io/docs/reference/config/project-descriptor/ +[registry]: https://buildpacks.io/docs/for-buildpack-authors/how-to/distribute-buildpacks/publish-buildpack/ +[windows]: https://buildpacks.io/docs/for-app-developers/how-to/special-cases/build-for-windows/ diff --git a/content/docs/for-app-developers/how-to/build-inputs/specify-default-launch-process.md b/content/docs/for-app-developers/how-to/build-inputs/specify-default-launch-process.md index a38a8294e..955319548 100644 --- a/content/docs/for-app-developers/how-to/build-inputs/specify-default-launch-process.md +++ b/content/docs/for-app-developers/how-to/build-inputs/specify-default-launch-process.md @@ -4,19 +4,15 @@ weight=99 summary="Buildpacks can define multiple processes for an application image. Specify which process should be the default." +++ -Buildpacks usually define the default process type for an application, while retaining the ability for a user to specify their desired default process. +While buildpacks usually define the default process type for an application, end users may specify the desired default process. -To configure the `build` to work differently from the default behavior: +To specify the default process: -* You first need to know what processes would be contributed by the buildpacks running in your build. -* Once known, you can append the following flag to the `pack build` command +* You first need to know what named process types might be contributed by the buildpacks in your build; for more information, see docs for [running the application][Run the application] +* Append the following flag to the `pack build` command: ```bash -pack build --default-process ` # must be a valid process name in launch.toml +pack build --default-process ` # must be a valid process name ``` -If this flag is not provided by the user, `pack` will provide the process type as `web` to the `lifecycle`. - ->As an app developer, you can specify the default process for an application. However, buildpacks-built images can contain multiple process types, to see how to invoke each one, see the [Run the application] page. - [Run the application]: https://buildpacks.io/docs/for-app-developers/how-to/build-outputs/specify-launch-process/ diff --git a/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md b/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md index f40972ed8..b1967f764 100644 --- a/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md +++ b/content/docs/for-app-developers/how-to/build-outputs/inspect-app.md @@ -15,7 +15,7 @@ Information includes: * Whether the run-image can be rebased with a new version through the `Rebasable` label or not * And more...! -`Pack` offers a built-in command to help you inspect the resultant image and view some of its contents as shown below: +`pack` offers a command to help you inspect the application image and view some of its contents as shown below: ```bash pack inspect-image test-node-js-app @@ -39,13 +39,13 @@ Processes: Apart from the above standard metadata, buildpacks can also populate information about the dependencies they have provided in form of a `Software Bill-of-Materials` or [SBOM]. -As already mentioned, buildpacks help you get an `OCI` images that are constructed in a way that’s easy to understand and update with each of the layers being meaningful and independent of all other layers. You can get more details about each layer and how it was created to better understand how the [Build] actually worked. +Buildpacks-built images are constructed in a way that’s easy to understand, with each of the layers being meaningful and independent of all other layers. You can get more details about each layer and how it was created to better understand how the [build] actually worked. -There are some available tools that help you achieve this and understand what is contained in your `OCI` image; a popular one is [Dive]. +There are a number of available tools that can help you achieve this and understand what is contained in your `OCI` image; a popular one is [dive]. -Dive can help you inspect `OCI` images, view their layers and each layer's details. If you were to build an `OCI` image following the [multi process app] example and run `Dive` on the generated image, you'll be presented with some detailed information about all of the image layers and understand what is in each layer. +`Dive` can help you inspect `OCI` images and view their layers and each layer's details. If you were to build an `OCI` image following the [multi process app] example and run `dive` on the generated image, you'll be presented with some detailed information about all of the image layers and the contents of each layer. -You can use `Dive` as follows: +You can use `dive` as follows: ```bash dive multi-process-app diff --git a/content/docs/for-app-developers/how-to/build-outputs/specify-launch-process.md b/content/docs/for-app-developers/how-to/build-outputs/specify-launch-process.md index b099da27b..419f35f99 100644 --- a/content/docs/for-app-developers/how-to/build-outputs/specify-launch-process.md +++ b/content/docs/for-app-developers/how-to/build-outputs/specify-launch-process.md @@ -81,7 +81,7 @@ docker run --rm -p 8080:8080 multi-process-app ``` ->As an app developer, you can specify what the default process is, see [specify default launch process][default-process] page for more information. +>As an app developer, you can specify what the default process is; see the [specify default launch process][default-process] page for more information. #### Default process type with additional arguments diff --git a/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md b/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md index e77e17f63..3146be9c5 100644 --- a/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md +++ b/content/docs/for-app-developers/how-to/build-outputs/understand-failures.md @@ -4,6 +4,35 @@ weight=99 summary="How to troubleshoot when things go wrong." +++ -While `Buildpacks` help developers transform applications' source code into container images that can run on any cloud, creating an error-free experience remains far from achieved. +While `Buildpacks` help developers transform source code into container images that can run on any cloud, creating an error-free experience remains far from achieved. -This guide explores some of the most common issues that may prevent image build completion and provides troubleshooting tips to help end-users navigate these issues. +This guide catalogs some commonly reported issues that may prevent image build completion and provides troubleshooting tips to help end-users navigate these issues. + +If you would like to report an issue, please open a PR against this page using the included template (see bottom of page in Markdown). + +#### Issue: `ERROR: failed to build: failed to fetch base layers: saving image with ID "sha256:" from the docker daemon: Error response from daemon: unable to create manifests file: NotFound: content digest sha256:: not found` + +**Occurs when**: building and saving to a docker daemon +**Analysis**: this seems to indicate a problem with the underlying image store in `Docker` +**Remediation**: remove existing images with `docker image prune` (potentially, from multiple storage drivers if switching between `overlay2` and `containerd`) +**Related error messages**: + +* `ERROR: failed to initialize analyzer: getting previous image: get history for image "test": Error response from daemon: NotFound: snapshot sha256: does not exist: not found` +* `ERROR: failed to export: saving image: failed to fetch base layers: open /tmp/imgutil.local.image./blobs/sha256/: no such file or directory` + +**For more information**: + +* [Issue link on GitHub](https://github.com/buildpacks/pack/issues/2270) +* [Slack thread](https://cloud-native.slack.com/archives/C0331B61A1Y/p1717422902392339?thread_ts=1717185700.984459&cid=C0331B61A1Y) +* [Another Slack thread](https://cloud-native.slack.com/archives/C033DV8D9FB/p1730243369203799) + + \ No newline at end of file From f355ab5b0be97227d274ab66ea8dd743993657a8 Mon Sep 17 00:00:00 2001 From: Robert Gogolok Date: Mon, 18 Nov 2024 00:02:37 +0100 Subject: [PATCH 10/12] Provide output for image run Signed-off-by: Robert Gogolok --- .../tutorials/lifecycle/_index.md | 37 ++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md index e1c728936..c52e74cb1 100644 --- a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md +++ b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md @@ -430,8 +430,43 @@ Finally, you can run the exported image as follows: docker run -it apps/bash-script ./app.sh ``` +The output should look similar to the following: + ```text -OUTPUT PLACEHOLDER + + |'-_ _-'| ____ _ _ _ _ _ + | | | | _ \ (_)| | | | | | (_) + '-_|_-' | |_) | _ _ _ | | __| | _ __ __ _ ___ | | __ ___ _ ___ +|'-_ _-'|'-_ _-'| | _ < | | | || || | / _` ||'_ \ / _\ | / __|| |/ // __| | | / _ \ +| | | | | | |_) || |_| || || || (_| || |_) || (_| || (__ | < \__ \ _ | || (_) | + '-_|_-' '-_|_-' |____/ \__,_||_||_| \__,_|| .__/ \__,_| \___||_|\_\|___/(_)|_| \___/ + | | + |_| + + +Here are the contents of the current working directory: +.: +total 24 +drwxr-xr-x 3 502 dialout 4096 Jan 1 1980 . +drwxr-xr-x 1 502 root 4096 Jan 1 1980 .. +-rw-r--r-- 1 502 dialout 692 Jan 1 1980 README.md +-rwxr-xr-x 1 502 dialout 736 Jan 1 1980 app.sh +drwxr-xr-x 3 502 dialout 4096 Jan 1 1980 bash-script-buildpack +-rw-r--r-- 1 502 dialout 202 Jan 1 1980 project.toml + +./bash-script-buildpack: +total 16 +drwxr-xr-x 3 502 dialout 4096 Jan 1 1980 . +drwxr-xr-x 3 502 dialout 4096 Jan 1 1980 .. +drwxr-xr-x 2 502 dialout 4096 Jan 1 1980 bin +-rw-r--r-- 1 502 dialout 226 Jan 1 1980 buildpack.toml + +./bash-script-buildpack/bin: +total 16 +drwxr-xr-x 2 502 dialout 4096 Jan 1 1980 . +drwxr-xr-x 3 502 dialout 4096 Jan 1 1980 .. +-rwxr-xr-x 1 502 dialout 345 Jan 1 1980 build +-rwxr-xr-x 1 502 dialout 242 Jan 1 1980 detect ``` ## Wrapping up From ae50e3bf0dea66e75a70221b4a2e0c1f1c3d5f2a Mon Sep 17 00:00:00 2001 From: Robert Gogolok Date: Tue, 19 Nov 2024 10:00:53 +0100 Subject: [PATCH 11/12] Linux arm64 launcher required for Mac users (#788) When a Mac users exports the artifacts built by the `builder`, the `launcher` executable packaged into an OCI image must be linux arm64 in the tutorial. Signed-off-by: Robert Gogolok --- .../docs/for-platform-operators/tutorials/lifecycle/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md index e1c728936..9975a06fe 100644 --- a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md +++ b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md @@ -42,7 +42,7 @@ Now that you’re set up, let’s build our `Bash` application and dive deeper i As a starting step, you need to build the `lifecycle` in order to use its phases. This could be done by navigating to the `lifecycle` directory and executing one of the following commands, depending on your system architecture. * `make build-linux-amd64` for `AMD64` architectures (for Linux users) -* `make build-darwin-arm64` for `ARM64` architectures (for Mac users) +* `make build-darwin-arm64 && make build-linux-arm64-launcher` for `ARM64` architectures (for Mac users) It's recommended to check the [lifecycle releases][releases] page to download binaries based on your system. > Please note that the entire process is most easily followed on Linux systems From 02f1cbf2a76e2b0dd2c6ad634a4b71a32abbbf2e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 25 Nov 2024 20:33:40 +0000 Subject: [PATCH 12/12] Bump buildpacks/github-actions from 5.8.1 to 5.8.2 (#789) Bumps [buildpacks/github-actions](https://github.com/buildpacks/github-actions) from 5.8.1 to 5.8.2. - [Release notes](https://github.com/buildpacks/github-actions/releases) - [Commits](https://github.com/buildpacks/github-actions/compare/v5.8.1...v5.8.2) --- updated-dependencies: - dependency-name: buildpacks/github-actions dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index cbf93b47f..ae7764b96 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -24,7 +24,7 @@ jobs: - name: Install Dependencies run: sudo apt-get install make curl jq - name: Install pack - uses: buildpacks/github-actions/setup-pack@v5.8.1 + uses: buildpacks/github-actions/setup-pack@v5.8.2 with: pack-version: '0.31.0' - name: Test