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.
If using pack, run pack config experimental true, or add experimental = true to your ~/.pack/config.toml file to enable experimental features.
If using the lifecycle directly, set the CNB_EXPERIMENTAL_MODE environment variable.
The following features are experimental for pack:
pack manifest commandspack buildpack --flattenpack build --interactiveThe following features are experimental for lifecycle:
For more information and to look at an example of how this might be valuable, see Export to OCI layout format on disk.
+ + + +Certain features are considered experimental and susceptible to change in future API versions.
This page is a stub! The CNB project is applying to Google Season of Docs to receive support for improving our documentation. Please check back soon.
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
- +While buildpacks usually define the default process type for an application, end users may specify the desired default process.
+To specify the default process:
+pack build command:pack build --default-process <process name> <image name>` # <process name> must be a valid process name
+Rebasable label or notpack offers a command to help you inspect the application image and view some of its contents as shown below:
pack inspect-image test-node-js-app
You should see the following:
Run Images:
@@ -928,6 +932,14 @@ Inspect your application image
TYPE SHELL COMMAND ARGS WORK DIR
web (default) bash node-js app.js /workspace
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.
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 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 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:
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.
For this example we will use the hello-processes buildpack from our samples repo so make sure you have it cloned locally.
Let’s build the app.
-pack build multi-process-app \
- --builder cnbs/sample-builder:alpine \
- --buildpack samples/java-maven \
- --buildpack samples/buildpacks/hello-processes/ \
- --path samples/apps/java-maven/
-pack build multi-process-app \
+ --builder cnbs/sample-builder:alpine \
+ --buildpack samples/java-maven \
+ --buildpack samples/buildpacks/hello-processes/ \
+ --path samples/apps/java-maven/
+If you inspect the app image with pack, you will see multiple process types defined:
pack inspect-image multi-process-app
-pack inspect-image multi-process-app
+The output should look similar to the below:
-Inspecting image: multi-process-app
-
-REMOTE:
-(not present)
-
-LOCAL:
-
-Stack: io.buildpacks.samples.stacks.alpine
-
-Base Image:
- Reference: f5898fb2b30c2b66f5a69a424bae6473259fa48b387df35335f04332af7f1091
- Top Layer: sha256:700c764e7c5d5c75e6a0fc7d272b7e1c70ab327c03fbdf4abd9313e5ec3217f7
-
-Run Images:
- cnbs/sample-base-run:alpine
-
-Rebasable: true
-
-Buildpacks:
- ID VERSION HOMEPAGE
- samples/java-maven 0.0.2 https://github.com/buildpacks/samples/tree/main/buildpacks/java-maven
- samples/hello-processes 0.0.1 https://github.com/buildpacks/samples/tree/main/buildpacks/hello-process
-
-Processes:
- TYPE SHELL COMMAND ARGS
- web (default) bash java -jar target/sample-0.0.1-SNAPSHOT.jar
- sys-info bash /layers/samples_hello-processes/sys-info/sys-info.sh
-Notice that the java-maven buildpack defined web as the default process type.
+
Inspecting image: multi-process-app
+
+REMOTE:
+(not present)
+
+LOCAL:
+
+Stack: io.buildpacks.samples.stacks.alpine
+
+Base Image:
+ Reference: f5898fb2b30c2b66f5a69a424bae6473259fa48b387df35335f04332af7f1091
+ Top Layer: sha256:700c764e7c5d5c75e6a0fc7d272b7e1c70ab327c03fbdf4abd9313e5ec3217f7
+
+Run Images:
+ cnbs/sample-base-run:alpine
+
+Rebasable: true
+
+Buildpacks:
+ ID VERSION HOMEPAGE
+ samples/java-maven 0.0.2 https://github.com/buildpacks/samples/tree/main/buildpacks/java-maven
+ samples/hello-processes 0.0.1 https://github.com/buildpacks/samples/tree/main/buildpacks/hello-process
+
+Processes:
+ TYPE SHELL COMMAND ARGS
+ web (default) bash java -jar target/sample-0.0.1-SNAPSHOT.jar
+ sys-info bash /layers/samples_hello-processes/sys-info/sys-info.sh
+Notice that the java-maven buildpack defined web as the default process type.
If we had run the pack build command above with --default-process sys-info, sys-info would be the default process for the app image!
Buildpacks are designed to give you much flexibility in how you run your app. The lifecycle includes a binary called the launcher which is present in the final app image and is responsible for starting your app.
@@ -952,45 +955,48 @@
launcher will source any profile scripts (for non-direct processes) and set buildpack-provided environment variables in the app’s execution environment before starting the app process.
If you would like to run the default process, you can simply run the app image without any additional arguments:
-docker run --rm -p 8080:8080 multi-process-app
-docker run --rm -p 8080:8080 multi-process-app
++As an app developer, you can specify what the default process is; see the specify default launch process page for more information.
+
If you would like to pass additional arguments to the default process, you can run the app image with the arguments specified in the command:
-docker run --rm -p 8080:8080 multi-process-app --spring.profiles.active=mysql
-docker run --rm -p 8080:8080 multi-process-app --spring.profiles.active=mysql
+To run a non-default process type, set the process type as the entrypoint for the run container:
-docker run --rm --entrypoint sys-info multi-process-app
-docker run --rm --entrypoint sys-info multi-process-app
+You can pass additional arguments to a non-default process type:
-docker run --rm --entrypoint sys-info multi-process-app --spring.profiles.active=mysql
-docker run --rm --entrypoint sys-info multi-process-app --spring.profiles.active=mysql
+You can even override the buildpack-defined process types:
-docker run --rm --entrypoint launcher -it multi-process-app bash
-docker run --rm --entrypoint launcher -it multi-process-app bash
+Now let’s exit this shell and run an alternative entrypoint -
-exit
-docker run --rm --entrypoint launcher -it multi-process-app echo hello "$WORLD" # $WORLD is evaluated on the host machine
-docker run --rm --entrypoint launcher -it multi-process-app echo hello '$WORLD' # $WORLD is evaluated in the container after profile scripts are sourced
-exit
+docker run --rm --entrypoint launcher -it multi-process-app echo hello "$WORLD" # $WORLD is evaluated on the host machine
+docker run --rm --entrypoint launcher -it multi-process-app echo hello '$WORLD' # $WORLD is evaluated in the container after profile scripts are sourced
+An entire script may be provided as a single argument:
-docker run --rm --entrypoint launcher -it multi-process-app 'for opt in $JAVA_OPTS; do echo $opt; done'
-docker run --rm --entrypoint launcher -it multi-process-app 'for opt in $JAVA_OPTS; do echo $opt; done'
+By passing -- before the command, we instruct the launcher to start the provided process without bash.
Note that while buildpack-provided environment variables will be set in the execution environment, no profile scripts will be sourced (as these require bash):
docker run --rm --entrypoint launcher multi-process-app -- env # output will include buildpack-provided env vars
-docker run --rm --entrypoint launcher multi-process-app -- echo hello "$WORLD" # $WORLD is evaluated on the host machine
-docker run --rm --entrypoint launcher multi-process-app -- echo hello '$WORLD' # $WORLD is not evaluated, output will include string literal `$WORLD`
-docker run --rm --entrypoint launcher multi-process-app -- env # output will include buildpack-provided env vars
+docker run --rm --entrypoint launcher multi-process-app -- echo hello "$WORLD" # $WORLD is evaluated on the host machine
+docker run --rm --entrypoint launcher multi-process-app -- echo hello '$WORLD' # $WORLD is not evaluated, output will include string literal `$WORLD`
+You can bypass the launcher entirely by setting a new entrypoint for the run container:
-docker run --rm --entrypoint bash -it multi-process-app # profile scripts have NOT been sourced and buildpack-provided env vars are NOT set in this shell
-docker run --rm --entrypoint bash -it multi-process-app # profile scripts have NOT been sourced and buildpack-provided env vars are NOT set in this shell
+To learn more about the launcher, see the platform spec.
diff --git a/docs/for-app-developers/how-to/build-outputs/understand-failures/index.html b/docs/for-app-developers/how-to/build-outputs/understand-failures/index.html index a7804d3be..aebbd792b 100644 --- a/docs/for-app-developers/how-to/build-outputs/understand-failures/index.html +++ b/docs/for-app-developers/how-to/build-outputs/understand-failures/index.html @@ -220,6 +220,9 @@This page is a stub! The CNB project is applying to Google Season of Docs to receive support for improving our documentation. Please check back soon.
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
- +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 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).
+ERROR: failed to build: failed to fetch base layers: saving image with ID "sha256:<sha256>" from the docker daemon: Error response from daemon: unable to create manifests file: NotFound: content digest sha256:<sha256>: not foundOccurs 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:<sha256> does not exist: not foundERROR: failed to export: saving image: failed to fetch base layers: open /tmp/imgutil.local.image.<identifier>/blobs/sha256/<sha256>: no such file or directoryFor more information:
+ + diff --git a/docs/for-app-developers/how-to/index.html b/docs/for-app-developers/how-to/index.html index 109405946..519e1840d 100644 --- a/docs/for-app-developers/how-to/index.html +++ b/docs/for-app-developers/how-to/index.html @@ -220,6 +220,9 @@